OpenAPI

OpenAPI Comment Parser : un outil IBM pour analyser les commentaires dans le code d'une API et générer la documentation correspondante

Soumis par fredericmazue le

Les développeurs ont besoin d'instructions sur la façon d'utiliser une API et ils ont besoin d'un moyen de l'essayer. Une bonne documentation satisfait ces deux besoins. Pour aider à générer une telle documentation, conforme aux spécifications OpenAPI, IBM propose OpenAPI Comment Parser

OpenAPI Comment Parser a pour objectif de donner aux développeurs d'API un moyen de générer une documentation conforme aux spécifications OpenAPI à partir de commentaires en ligne dans leur code. Lorsque la spécification OpenAPI vit dans le code, les développeurs sont beaucoup plus susceptibles de la maintenir à jour à mesure que leur code change, souligne IBM.

OpenAPI Comment Parser est une bibliothèque est conçue pour Node.js, mais elle peut fonctionner avec n'importe quel langage qui utilise ce style de commentaires:

/**
* GET /users/{userId}
* @summary Returns a user by ID.
* @pathParam {int64} userId - The user's ID.
* @response 200 - OK
*/

OpenAPI Comment Parser est un logiciel libre sous licence Apache 2.0, disponivle sur GitHub.

[video:https://www.youtube.com/watch?v=-Z9Zn8RHf0c autoplay:0]

GitHub ouvre une description OpenAPI de son API REST

Soumis par fredericmazue le

Afin d'améliorer la façon dont les développeurs peuvent interagir avec son API REST, GitHub a ouvert une description OpenAPI de celle-ci.

Pour mémoire, la spécification OpenAPI (OAS) définit une description d'interface standard, indépendante du langage de programmation pour les API HTTP.  Cette description d'interface permet aux humains et aux ordinateurs de découvrir et de comprendre les capacités d'un service sans avoir besoin d'accéder au code source, à une documentation supplémentaire ou à l'inspection du trafic réseau. Grâce à une telle description, un consommateur peut comprendre et interagir avec le service distant avec un minimum de logique d'implémentation.

La description GitHub OpenAPI contient plus de 600 opérations exposées par l'API REST. Pour l'exploration visuelle de l'API, vous pouvez charger la description en tant que collection Postman

Cette description est actuellement en phase bêta. Décrire une API vieille de 12 ans n'est pas une tâche facile, souligne GitHub

La description OpenAPI de l'API REST GitHub est un logiciel libre sous licence MIT, disponible sur ... GitHub :-)