Zuvor haben Sie möglicherweise Swagger 2.0 (auch bekannt als OAS 2) verwendet, aber jetzt ist es an der Zeit, auf die OpenAPI Specification (OAS) 3 zu aktualisieren. In diesem Artikel werden wir die wichtigsten Punkte des Upgrade-Prozesses und die Grundlagen der Dokumentation von APIs mit OAS 3 umreißen.
Einige dieser Punkte könnten immer noch für die vorherigen OAS 2 (ehemals Swagger) Dokumente gelten, aber es lohnt sich, dies zu beachten, da ich sie möglicherweise zuvor nicht vollständig hervorgehoben habe.
Die Codebeispiele in diesem Artikel stammen aus der OAS 3-Spezifikation von bookmarks.dev-api, die in der Datei openapi.yaml auf GitHub verfügbar ist. Die Ergebnisse können unter bookmarks.dev/api/docs/ eingesehen werden.
Hier sind zehn wichtige Überlegungen:
1. Lesen Sie das Spezifikationsdokument
Lesen Sie den Artikel "A Guide to What's New in OpenAPI 3.0", der einige der wichtigsten Aktualisierungen in der neuesten Version von OAS vorstellt und detaillierte Einblicke in das bietet, was Sie beim Übergang von OAS 2.0 zu OAS 3.0 wissen müssen. Dieser Artikel basiert auf dem 1-stündigen Webinar "OpenAPI 3.0, And What it Means for the Future of Swagger".
2. Verwenden Sie einen Converter Web Service
Verwenden Sie den OpenAPI/Swagger 2.0 to OpenAPI 3.0 Converter Web Service, um Ihre Swagger-Spezifikationen in OpenAPI 3.0 umzuwandeln.
Er ist online verfügbar unter https://converter.swagger.io/, und Sie können ihn auch als Docker-Image verwenden:
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3. Validieren Sie Ihre Spezifikation und erstellen Sie eine Vorschau mit Swagger Editor
Swagger Editor ermöglicht es Ihnen, YAML-formatierte Swagger-API-Spezifikationen in Ihrem Webbrowser zu bearbeiten und die Dokumentation sofort in der Vorschau anzuzeigen.
Sie können es online oder als npm-veröffentlichte Version oder als Docker-Image verwenden. Weitere Details finden Sie in der README des Projekts.
4. Präsentieren Sie Ihre Dokumentation mit Swagger UI
Swagger UI ist eine Sammlung von HTML-, JavaScript- und CSS-Ressourcen, die dynamisch eine schöne Dokumentation für Swagger-konforme APIs generieren.
Sie können es direkt verwenden, wie ich, indem Sie über eine API-Route auf die Swagger UI-Dokumentation zugreifen, z. B. bookmarks.dev/api/docs/. Hier ist ein Codeausschnitt aus app.js:
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
Das Einbeziehen der offenen Spezifikationsdatei (openapi.yaml) in Ihren nodemon-Watch (z. B. nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) kann hilfreich sein, da Sie die UI neu laden können, ohne den ExpressJS-Server manuell neu starten zu müssen.
4.1. Verwenden Sie swagger-jsdoc für den Code-First-Ansatz
Ein weiterer bemerkenswerter Punkt ist, dass Sie swagger-jsdoc verwenden können, um Swagger über JSDoc-Annotationen in Ihren Code zu integrieren. Das swagger-jsdoc-Projekt geht davon aus, dass Sie vorhandenen, aktiven, funktionierenden Code so dokumentieren möchten, dass er "zum Leben erweckt" wird, und eine Spezifikation generiert, die in andere Swagger-Tools eingespeist werden kann, anstatt umgekehrt.
Derzeit verwalte ich die Dokumentation in einer einzigen openapi.yaml-Datei, aber ich werde möglicherweise in Zukunft die Verwendung in Betracht ziehen.
5. Gruppieren Sie Operationen mithilfe von Tags
Sie können jeder API-Operation eine Tag-Liste zuweisen, wodurch es für Swagger UI und Swagger Editor bequem wird, Operationen nach Tags anzuzeigen. Um die Sortierung in Swagger UI zu steuern, müssen Sie sie als globale Tags auf der Stammebene hinzufügen. Sie können dort auch Beschreibungen und Links zu externen Dokumenten hinzufügen.
Hier sind die Tags, die ich für die API verwende:
yamlCopy code
tags:- name: rootdescription: Used to mark root endpoints- name: versiondescription: Access project version and gitSha1- name: public-bookmarksdescription: Access public bookmarks- name: personal-bookmarksdescription: Operations on personal bookmarks- name: user-datadescription: Operations on user data- name: helperdescription: Helper endpoints/operations
6. Geben Sie API-Basis-URLs mit Servern an
In OpenAPI 3.0 verwenden Sie das Servers-Array, um eine oder mehrere Basis-URLs für die API anzugeben. Server ersetzen die Schlüsselwörter host, basePath und schemes, die in OpenAPI 2.0 verwendet werden. Jeder Server hat eine URL und eine optionale Beschreibung im Markdown-Format.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: Local server for development- url: https://www.bookmarks.dev/apidescription: Main (production) server
7. Definieren und Wiederverwenden von Ressourcen mit Komponenten
Oftmals teilen sich mehrere API-Operationen gemeinsame Parameter oder geben dieselbe Antwortstruktur zurück. Um Code-Duplizierung zu vermeiden, können Sie gemeinsame Definitionen im globalen Komponentenabschnitt platzieren und mit $ref darauf verweisen.
Für die Antwort, die mehreren Operationen gemeinsam ist, bei denen eine Liste von Lesezeichen angezeigt wird, definiere ich beispielsweise eine BookmarkListResponse unter components > responses:
components:responses:BookmarkListResponse:description: List of bookmarkscontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
Und dann verweise ich in verschiedenen Operationen darauf, wie z. B. get-public-bookmarks:
yamlCopy code
/public/bookmarks:get:summary: Return a list of public bookmarks using query parameters.tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: OK$ref: "#/components/responses/BookmarkListResponse"
Beachten Sie die oben erwähnte locationQueryParam. Sie ist unter components > parameters definiert und wird an mehreren Stellen in der API-Spezifikation referenziert, einschließlich des oben gezeigten Beispiels.
8. Fügen Sie Beispiele zur Verdeutlichung hinzu
Sie können Beispiele zu Parametern, Eigenschaften und Objekten hinzufügen, um die Spezifikation Ihres Webdienstes übersichtlicher zu gestalten. Beispiele können von Tools und Bibliotheken für Ihre API gelesen werden. Beispielsweise kann ein Mock-API-Tool Beispielwerte verwenden, um Mock-Anforderungen zu generieren. Sie können Beispiele für Objekte, einzelne Eigenschaften und Operationsparameter mithilfe der Schlüssel example oder examples angeben.
Beispielsweise können Sie komplexe Werte als Beispiele für einen Suchtextparameter haben:
components:parameters:searchTextQueryParam:name: qin: querydescription: |
Search query (words separated by spaces). Special filters available:
* `lang:iso_language_code` - e.g., `lang:en` for English, `lang:es` for Spanish, `lang:de` for German bookmarks
* `site:site_URL` - e.g., return bookmarks from [www.codepedia.org](htt