Auparavant, vous utilisiez peut-être Swagger 2.0 (également connu sous le nom d'OAS 2), mais il est maintenant temps de passer à la spécification OpenAPI (OAS) 3. Dans cet article, nous allons présenter les points clés du processus de mise à niveau et les éléments essentiels de la documentation des API à l'aide d'OAS 3.
Certains de ces points peuvent encore s'appliquer aux documents OAS 2 précédents (anciennement connus sous le nom de Swagger), mais il est important de le noter car je ne les ai peut-être pas pleinement soulignés auparavant.
Les exemples de code de cet article sont extraits de la spécification OAS 3 de bookmarks.dev-api, qui est disponible dans le fichier openapi.yaml sur GitHub. Les résultats peuvent être consultés sur bookmarks.dev/api/docs/.
Voici dix considérations clés :
1. Lisez le document de spécification
Lisez l'article "A Guide to What's New in OpenAPI 3.0", qui partage certaines des principales mises à jour de la dernière version d'OAS et fournit des informations détaillées sur ce que vous devez savoir lors de la transition d'OAS 2.0 vers OAS 3.0. Cet article est basé sur le webinaire d'une heure "OpenAPI 3.0, et ce que cela signifie pour l'avenir de Swagger".
2. Utilisez un service Web de conversion
Utilisez le service Web de conversion OpenAPI/Swagger 2.0 vers OpenAPI 3.0 pour transformer vos spécifications Swagger en OpenAPI 3.0.
Il est disponible en ligne à l'adresse https://converter.swagger.io/, et vous pouvez également l'utiliser comme image Docker :
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3. Validez votre spécification et prévisualisez-la avec Swagger Editor
Swagger Editor vous permet de modifier les spécifications d'API Swagger au format YAML dans votre navigateur Web et de prévisualiser instantanément la documentation.
Vous pouvez l'utiliser en ligne ou en tant que version publiée par npm ou une image Docker. Pour plus de détails, reportez-vous au README du projet.
4. Présentez votre documentation avec Swagger UI
Swagger UI est un ensemble de ressources HTML, JavaScript et CSS qui génèrent dynamiquement une belle documentation pour les API conformes à Swagger.
Vous pouvez l'utiliser directement, comme moi, en accédant à la documentation Swagger UI via un itinéraire d'API, par exemple bookmarks.dev/api/docs/. Voici un extrait de code de 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));
L'inclusion du fichier de spécification ouvert (openapi.yaml) dans votre surveillance nodemon (par exemple, nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) peut être utile, vous permettant de recharger l'interface utilisateur sans redémarrer manuellement le serveur ExpressJS.
4.1. Utilisez swagger-jsdoc pour l'approche Code-First
Un autre point notable est que vous pouvez utiliser swagger-jsdoc pour intégrer Swagger via des annotations JSDoc dans votre code. Le projet swagger-jsdoc suppose que vous souhaitez documenter le code existant, actif et fonctionnel d'une manière qui lui "donne vie", en générant une spécification qui peut être intégrée à d'autres outils Swagger plutôt que l'inverse.
Actuellement, je gère la documentation dans un seul fichier openapi.yaml, mais je pourrais envisager de l'utiliser à l'avenir.
5. Regroupez les opérations à l'aide de balises
Vous pouvez attribuer une liste de balises à chaque opération d'API, ce qui permet à Swagger UI et Swagger Editor d'afficher facilement les opérations par balises. Pour contrôler le tri dans Swagger UI, vous devez les ajouter en tant que balises globales au niveau racine. Vous pouvez également y ajouter des descriptions et des liens vers des documents externes.
Voici les balises que j'utilise pour l'API :
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. Spécifiez les URL de base de l'API avec les serveurs
Dans OpenAPI 3.0, vous utilisez le tableau des serveurs pour spécifier une ou plusieurs URL de base pour l'API. Les serveurs remplacent les mots-clés host, basePath et schemes utilisés dans OpenAPI 2.0. Chaque serveur a une URL et une description facultative au format Markdown.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: Local server for development- url: https://www.bookmarks.dev/apidescription: Main (production) server
7. Définissez et réutilisez les ressources avec les composants
Souvent, plusieurs opérations d'API partagent des paramètres communs ou renvoient la même structure de réponse. Pour éviter la duplication de code, vous pouvez placer les définitions communes dans la section des composants globaux et y faire référence à l'aide de $ref.
Par exemple, pour la réponse commune à plusieurs opérations où une liste de signets apparaît, je définis une BookmarkListResponse sous components > responses :
components:responses:BookmarkListResponse:description: List of bookmarkscontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
Et ensuite, j'y fais référence dans différentes opérations, telles que 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"
Notez le locationQueryParam mentionné ci-dessus. Il est défini sous components > parameters et référencé à plusieurs endroits dans la spécification de l'API, y compris l'exemple montré ci-dessus.
8. Ajoutez des exemples pour plus de clarté
Vous pouvez ajouter des exemples aux paramètres, aux propriétés et aux objets pour rendre la spécification de votre service Web plus claire. Les exemples peuvent être lus par les outils et les bibliothèques de votre API. Par exemple, un outil d'API factice peut utiliser des exemples de valeurs pour générer des requêtes factices. Vous pouvez spécifier des exemples pour les objets, les propriétés individuelles et les paramètres d'opération à l'aide des clés example ou examples.
Par exemple, vous pouvez avoir des valeurs complexes comme exemples pour un paramètre de texte de recherche :
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
