Notwendigkeit, ein API-Dokument für eine vorhandene Anwendung zu erstellen, die mit nodejs/express

Question

geschrieben wird Ich habe ein paar private apis in plain old express geschrieben. Es ist Zeit, es rauszulassen und eine Dokumentation zu liefern.

Was ich nicht will (zumindest noch) es meine Express-App neu zu schreiben, um die API-Dokumentation in den Code zu integrieren. Hauptsächlich da ich nicht sicher bin, welches Framework oder welche Spezifikation ich verwenden soll, um meine API zu dokumentieren, möchte ich mich nicht wirklich auf eine bestimmte Sache festlegen.

Ich möchte das Dokument als Teil einer Unterressource unter meiner API dienen (dh ich möchte nicht einen anderen Server oder Subdomain ausführen). Vielleicht '/ api/docs'. Ein Plus wäre auch eine Benutzeroberfläche, die ich in meiner App einbetten könnte, die die Dokumente analysieren könnte und zumindest eine schöne Präsentation der Dokumente in HTML bieten würde (API-Interaktion ist ein Plus).

Dinge wie https://github.com/swagger-api/swagger-node-express sind cool, aber würde mich erfordern, alle meine Express-Code neu zu schreiben, um swagger zu integrieren. An diesem Punkt habe ich eine große Investition und bin eng mit Prahlerei verbunden.

Gibt es eine Möglichkeit, Swagger oder Jodocs oder etwas anderes zu servieren, um meine API auf eine Weise zu dokumentieren, die für bestehende Routen minimal invasiv ist?

EDIT:

Ich kann den Swagger spec aus einer Hand geschrieben doc absitzen. Problem, das ich sehe, ist, dass Sie basePath im swagger Dokument definieren müssen. Dies erlaubt mir nicht wirklich, einfach unter verschiedenen Domänen zu deployen.

Answer 1

Es gibt eine breite Palette von node.js Tools, um Swagger mit Ihrer Anwendung zu integrieren, und ich nehme an, dass sie verschiedene Möglichkeiten bieten, dies zu tun. Eine Liste solcher Integrationen finden Sie hier - https://github.com/webron/swagger-spec/#nodejs - aber ich kann Ihnen sagen, dass es da draußen zusätzliche Tools gibt, die dort nicht aufgeführt sind. Sie können versuchen, Github für Swagger und Node/Express zu suchen.

Wie für die manuelle Spezifikation und die BasePath - Swagger 2.0 löst das tatsächlich für Sie. Sie können den Online-Editor - http://editor.swagger.io - verwenden, um Ihre Spezifikationen in ein benutzerfreundlicheres YAML-Formular zu schreiben, das Sie dann in JSON exportieren können. Im Gegensatz zu Swagger 1.2 und früheren Versionen ist der basePath jetzt in drei Eigenschaften unterteilt: schemes (http, https), host (Domäne, Port) und basePath (der Stammkontext der Anwendung). Keine dieser Eigenschaften ist obligatorisch, und alle sind standardmäßig auf die Datei swagger.json eingestellt (die Spezifikation selbst). schemes Standardeinstellungen für den Systemdienst Die Swagger.json, host Standardwerte für den Host, der für das Serving von swagger.json verwendet wird, und basePath sind \, sofern nicht explizit angegeben. Ich glaube, dies sollte Ihre Bedenken bezüglich des basePaths lösen.