L’open source est un moteur de l’innovation qui a changé le destin de nombreux projets, grâce à la contribution d’une communauté importante. Parmi ceux-ci, figure le projet Swagger.Swagger est un projet open source lancé par une Startup en 2010. L’objectif est de mettre en place un Framework qui va permettre aux développeurs de documenter et de designer des API, tout en maintenant une synchronisation avec le code. Swagger est un framework libre utilisé par bon nombre de développeurs pour la définition et la création des services Restful pour leurs API.
Parallèlement au développement du Framework, une spécification Swagger a été mise en place pour définir le standard à respecter pour designer et documenter son API. Le projet a attiré l’attention de nombreux développeurs, et est devenu la technologie la plus populaire pour designer et décrire les API RESTful.
L’intérêt de l’industrie pour Swagger a poussé des grandes enseignes du numérique à se joindre au développement du projet. Google, IBM ou encore Microsoft ont rejoint SmartBear Software, l’entreprise responsable du développement de la spécification Swagger et les outils associés, pour faire évoluer ce dernier.
En novembre 2015, le projet Swagger Specification a été renommé OpenAPI Specification (OAS) et est passé sous la gouvernance de la fondation Linux. L’OPEN API Initiative a été créé par la fondation pour offrir un cadre de travail aux entreprises participantes. Le projet a été également migré vers un nouveau dépôt sur GitHub. En plus des membres fondateurs (entre autres 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal et Restlet), plusieurs autres grandes enseignes technologiques ont rejoint l’initiative, dont Oracle, Adobe, SAP, SalesForce, etc. La fondation Linux a expliqué que ce projet vise l’élaboration de spécifications standards qui fourniront des métadonnées Restful pour les API.
Selon le GitHub du projet, la spécification OpenAPI définit une description d'interface standard indépendante du langage de programmation pour les API REST, qui permet à la fois aux humains et aux machines de découvrir et comprendre les capacités offertes par un service sans avoir besoin d’accéder à son code, consulter une documentation supplémentaire, ou analyser le trafic réseau.
Open API Specification version 3.0.3
Open API Initiative a annoncé la disponibilité d’OAS 3.0.3. En tant que version de correctif, les modifications suivantes ont été apportées pour améliorer les spécifications en termes de lisibilité et de précision. Aucune de ces modifications ne modifie le comportement de la spécification :
- Clarification du fonctionnement du modèle de chemin.
- Clarification de la signification du contrôle de version sémantique tel qu'il s'applique à la spécification OpenAPI (notez qu'il s'agit du champ openapi et non du champ version).
- Modification de certains hyperliens de http à https.
- Ajout d'une explication selon laquelle l'enum de Server Variable Object ne doit pas être vide. Ce changement devrait être considéré comme un guide pour une restriction plus explicite dans la prochaine version majeure.
- Les chemins clarifiés sous Paths Object doivent commencer par une barre oblique.
- Clarification du comportement Path Item Object de $ref avec les champs frères.
- Correction de quelques exemples.
- Clarification de la structure de callbacks sous Operation Object.
- Clarification de la correspondance des paramètres de chemin.
- Exemple fixe pour la valeur pipeDelimited object.
- Correction de la description Callback Object.
- Clarification du comportement de nullable sous Schema Object.
- Correction des noms des flux OAuth2 dans la description Security Scheme Object.
- Amélioration de la description de la section Security Filtering.
Spécifications
Versions
La spécification OpenAPI est versionnée à l'aide de Semantic Versioning 2.0.0 (semver) et suit la spécification semver.
La partie major.minor du semver (par exemple 3.0) devra désigner l'ensemble de fonctionnalités OAS. En règle générale, les versions .patch corrigent les erreurs dans ce document, pas l'ensemble de fonctionnalités. L'outillage qui prend en charge OAS 3.0 devrait être compatible avec toutes les versions OAS 3.0.*. La version du correctif ne devrait pas être prise en compte par l'outillage, ne faisant aucune distinction entre 3.0.0 et 3.0.1 par exemple.
Chaque nouvelle version mineure de la spécification OpenAPI doit permettre à tout document OpenAPI valide par rapport à toute version mineure précédente de la spécification, dans la même version majeure, d'être mise à jour vers la nouvelle version de spécification avec une sémantique équivalente. Une telle mise à jour doit uniquement nécessiter la modification de la propriété openapi vers la nouvelle version mineure.
Par exemple, un document OpenAPI 3.0.2 valide, en changeant sa propriété openapi en 3.1.0, devra être un document OpenAPI 3.1.0 valide, sémantiquement équivalent au document OpenAPI 3.0.2 d'origine. De nouvelles versions mineures de la spécification OpenAPI doivent être écrites pour garantir cette forme de compatibilité descendante.
Un document...
La fin de cet article est réservée aux abonnés. Soutenez le Club Developpez.com en prenant un abonnement pour que nous puissions continuer à vous proposer des publications.