Documentation facile avec OpenAPI pour Express

Lorsque vous créez une API REST pour votre backend Node Express, vous devez la documenter correctement. Cette documentation est nécessaire afin que les développeurs externes ou les collègues dans votre équipe sachent à quoi s'attendre de votre contrat REST.

OpenAPI est un standard pour la documentation ouverte des terminaux REST. Il a évolué dans la société américaine SmartBear de la suite de produits Swagger. La spécification Swagger développée par SmartBear a été donnée en 2015 à la Linux Foundation sous le nom d'OpenAPI.

La spécification OpenAPI n'est pas seulement essentielle pour d'autres développeurs humains. Elle peut également être lue par des programmes informatiques pour accéder à l'application serveur sans avoir besoin d'accéder au code source.

Aujourd'hui, SmartBear continue de développer sa gamme de produits Swagger. Swagger Editor est d'ailleurs l'une des plus grandes marques du marché pour éditer facilement une spécification Open API.

Vous pouvez facilement installer l'Éditeur Swagger avec Docker:

docker pull swaggerapi/swagger-editor
docker run -d -p 8085:8080 swaggerapi/swagger-editor

L'interface web de l'éditeur est donc liée au port 8085 et lors de l'accès à l'application, un navigateur affiche un exemple de spécification dans le format YAML à gauche. Sur le côté droit se trouve la documentation fournie à l'utilisateur. Cette documentation ressemble à l'image en haut de cet article.

La spécification OpenAPI n'est pas difficile à comprendre pour quelqu'un qui a utilisé ou construit des API REST. Essayez-la en modifiant et avec en adaptatant le modèle à votre API. Si des erreurs surviennent, elles s'affichent sur la côté droit.

Ce rendu que vous pouvez voir sur le côté droit de l'Editeur Swagger, vous pouvez aussi facilement l'inclure dans votre propre application Express REST avec un package NPM appelé swagger-ui-express. Swagger UI est une collection de HTML, JavaScript et CSS qui génère une belle documentation.

La documentation produite par Swagger UI est généralement accessible via un endpoint comme /api-docs. Utilisez les lignes suivantes dans votre application Node Express pour lire vos spécifications du fichier YAML et le rendre accessible aux utilisateurs :

const swaggerUi = require('swagger-ui-express')
const YAML = require('yamljs')
const swaggerDocument = YAML.load('./swagger/swagger.yaml')

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument))

Ceci charge le fichier de spécification YAML OpenAPI dans le répertoire ./swagger et le rend sous /api-docs.

Certaines personnes vont d'abord développer la spécification OpenAPI et seulement ensuite démarrer avec la programmation réelle de l'application Express. D'autres ont une application déjà existante et veulent ajouter de la documentation plus tard. Dans les deux cas, l'éditeur Swagger et la spécification OpenAPI sont d'excellents outils.

Références et lectures complémentaires

• Swagger Editor : https://github.com/swagger-api/swagger-editor

• NPM package swagger-ui-express : https://github.com/scottie1984/swagger-ui-express

• What is the Difference Between Swagger and OpenAPI? https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi