OpenAPI Specification
OAS 3.1.1 Released!
La spécification OpenAPI est une spécification ouverte axée sur la communauté au sein de l'initiative OpenAPI, un projet collaboratif de la Linux Foundation.
La spécification OpenAPI (OES) définit une description de l'interface agnostique langage standard et de programmation pour les API HTTP. Cela permet aux humains et aux ordinateurs de découvrir et de comprendre les capacités d'un service sans nécessiter l'accès au code source, à une documentation supplémentaire ou à l'inspection du trafic réseau. Lorsqu'il est correctement défini via OpenAPI, un consommateur peut comprendre et interagir avec le service distant avec une quantité minimale de logique d'implémentation. Semblable à ce que les descriptions d'interface ont fait pour la programmation de niveau inférieur, la spécification OpenAPI supprime les conjectures en appelant un service.
Les cas d'utilisation pour les documents de définition d'API lisibles par machine incluent, mais sans s'y limiter: la documentation interactive; Génération de code pour la documentation, les clients et les serveurs; et automatisation des cas de test. Les documents OpenAPI décrivent les services API et sont représentés dans des formats YAML ou JSON. Ces documents peuvent être produits et servis statiquement ou générés dynamiquement à partir d'une application.
La spécification OpenAPI ne nécessite pas de réécriture des API existantes. Il ne nécessite pas de liaison de logiciel à un service - le service décrit peut même ne pas appartenir au créateur de sa description. Il exige cependant que les capacités du service soient décrites dans la structure de la spécification OpenAPI. Tous les services ne peuvent pas être décrits par OpenAPI - cette spécification n'est pas destinée à couvrir tous les styles possibles des API HTTP, mais inclut le support des API REST. La spécification OpenAPI n'impose pas un processus de développement spécifique tel que la conception-première ou le code-premier. Il facilite l'une ou l'autre technique en établissant des interactions claires avec une API HTTP.
Ce projet GitHub est le point de départ de OpenAPI. Ici, vous trouverez les informations dont vous avez besoin sur la spécification OpenAPI, des exemples simples de ce à quoi elles ressemblent et certaines informations générales concernant le projet.
Ce référentiel contient les sources Markdown pour toutes les versions de spécification OpenAPI publiées. Pour les notes de libération et la libération des versions candidates, reportez-vous à la page des versions.
Chaque dossier de ce référentiel, tel que les schémas et les tests, doit contenir des dossiers relatifs aux versions actuelles et précédentes de la spécification.
Si vous voulez simplement le voir fonctionner, consultez la liste des exemples actuels.
Vous cherchez à voir comment créer votre propre définition OpenAPI, la présenter ou l'utiliser autrement? Consultez la liste croissante des implémentations.
Le processus actuel d'élaboration de la spécification OpenAPI est décrit dans les directives contributives.
Le développement de la prochaine version de la spécification OpenAPI est guidé par le comité de direction technique (TSC). Ce groupe de commissaires apporte son expertise API, intègre les commentaires de la communauté et élargit le groupe de commistes, le cas échéant. Toute activité de développement sur les spécifications futures sera effectuée en tant que fonctionnalités et fusionnée dans cette branche. À la libération des spécifications futures, cette branche sera fusionnée à main .
Le TSC organise des conférences Web hebdomadaires pour examiner les demandes de traction ouvertes et discuter des problèmes ouverts liés à l'évolution des spécifications OpenAPI. La participation aux appels hebdomadaires et aux séances de travail prévues est ouverte à la communauté. Vous pouvez consulter l'intégralité du calendrier des réunions techniques OpenAPI en ligne.
L'initiative OpenAPI encourage la participation des particuliers et des entreprises. Si vous souhaitez participer à l'évolution de la spécification OpenAPI, envisagez de prendre les mesures suivantes:
Tous les commentaires ne peuvent pas être adaptés, et il peut y avoir des arguments solides pour ou contre un changement approprié pour la spécification.
Voir: Licence (Apache-2.0)
