Qu’est-ce qu’une spécification OpenAPI ?

OpenAPI Specification, anciennement Swagger, décrit différents aspects d’une API. Une spécification OpenAPI (spécification) décrit les points de terminaison, les paramètres et les réponses de l’API. Les spécifications OpenAPI sont écrites dans YAML ou JSON et sont utilisées par les outils pour générer de la documentation, des cas de test et des bibliothèques clientes. En ayant une spécification OpenAPI, les générateurs d’API peuvent s’assurer que leur API est décrite avec précision, plus accessible et plus facile à intégrer dans un large éventail d’applications et de services.

Voici pourquoi vous devez envisager d’avoir une spécification OpenAPI pour votre API :

• Documentez une API de manière standardisée. Documentez une spécification d’API dans un format cohérent et lisible par l’homme.
• Générez un Kit de développement logiciel (SDK) client. Utilisez des outils tels que Kiota pour automatiser la génération de bibliothèques clientes dans différents langages de programmation.
• Créez une API fictive. Créez des serveurs fictifs en fonction de la spécification de l’API, ce qui vous aide pendant les premières étapes de développement lorsque l’API réelle n’est pas encore implémentée.
• Améliorer la collaboration. Fournissez différentes équipes (front-end, back-end, QA) avec une compréhension claire des fonctionnalités et limitations de l’API, ce qui aide les nouveaux membres de l’équipe à se rattraper rapidement.
• Simplifiez les tests et la validation. Automatisez la validation des demandes et réponses d’API par rapport à la spécification, ce qui facilite l’identification des différences.
• Intégrer à des outils de gestion des API. Intégrez, déployez et surveillez facilement vos API avec de nombreux outils et passerelles de gestion des API, tels qu’Azure API Center et Gestion des API Azure.
• Simplifiez la configuration de la passerelle d’API. Utilisez des spécifications OpenAPI pour configurer des passerelles d’API et automatiser des tâches telles que le routage, les transformations et les paramètres de partage de ressources entre origines.

En utilisant des spécifications OpenAPI, vous pouvez créer des API bien conçues et documentées de manière cohérente. Ils sont également plus faciles à gérer et à utiliser à la fois en interne et par les consommateurs externes.

Vous n’avez pas encore de spécification OpenAPI ?

L’écriture d’une spécification manuelle pour une API qui existe déjà prend du temps et s’écarte de ce que l’API fait réellement. Une autre option consiste à enregistrer ce que l’API retourne et à générer la spécification à partir de celle-ci.

Approach	Ce que vous obtenez	Ce à quoi faire attention
Écrivez-le à la main	Contrôle total des descriptions et des exemples	Cela prend du temps et il s'éloigne de l'API réelle
Générez-le à partir d’annotations de code	Spécification qui reste synchronisée avec votre code	Vous avez besoin d’accéder au code de l’API, et le framework doit le prendre en charge
Générez-le à partir du trafic enregistré	Spécification pour n’importe quelle API que vous pouvez appeler, y compris celles que vous ne possédez pas	Il couvre uniquement les demandes que vous avez enregistrées, alors utilisez les parties de l’API dont vous avez besoin

Dev Proxy enregistre les demandes et les réponses entre votre application et une API, et génère une spécification OpenAPI à partir d’elles. Pour connaître les étapes, consultez Générer une spécification OpenAPI.

Étape suivante

Générer une spécification OpenAPI