Ich habe ein paar private Apis geschrieben in einfachen alten Express. Zeit, es rauszulassen und einige API-Dokumentation bereitzustellen.
Was ich nicht will (zumindest noch), dass ich meine Express-App neu schreibe, 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 bereitstellen (dh ich möchte keinen anderen Server oder eine andere 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 und zumindest eine schöne Präsentation der Dokumente in HTML bereitstellen könnte (API-Interaktion ist ein Plus).
Dinge wie Ссылка sind cool, aber würde erfordern, dass ich meinen ganzen ausdrücklichen Code umschreibe Integriere Prahlerei. An diesem Punkt habe ich eine große Investition und bin eng mit Swagger 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?
BEARBEITEN:
Ich könnte die Swagger-Spezifikation aus einem handgeschriebenen Dokument herausgeben. 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.
Es gibt eine breite Palette von node.js-Tools, um Swagger in Ihre Anwendung zu integrieren, und ich nehme an, dass sie verschiedene Möglichkeiten bieten, dies zu tun. Sie können eine Liste solcher Integrationen hier finden - Ссылка - aber ich kann Ihnen sagen, dass es zusätzliche Tools gibt da, 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 den basePath - Swagger 2.0 löst das tatsächlich für Sie. Sie können den Online-Editor - Ссылка - 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 ist standardmäßig auf den Schema-Dienst swagger.json, host auf den Host, der für die Auslieferung von swagger.json verwendet wird, und basePath wird \ angegeben, sofern nicht explizit angegeben. Ich glaube, das sollte Ihre Bedenken bezüglich des Basispfads lösen.