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 OpenAPI compatible avec OAS 3.*.* contient un champ openapi obligatoire qui désigne la version sémantique de l'OAS qu'il utilise. (Les documents OAS 2.0 contiennent un champ de version de niveau supérieur nommé swagger et la valeur "2.0".)
Format
Un document OpenAPI conforme à la spécification OpenAPI est lui-même un objet JSON, qui peut être représenté au format JSON ou YAML.
Par exemple, si un champ a une valeur de tableau, la représentation du tableau JSON sera utilisée:
Tous les noms de champ dans la spécification sont sensibles à la casse. Cela inclut tous les champs utilisés comme clés dans une carte, sauf indication contraire explicite selon laquelle les clés ne respectent pas la casse.
Le schéma expose deux types de champs: les champs fixes, qui ont un nom déclaré, et les champs à motifs, qui déclarent un modèle d'expression régulière pour le nom du champ.
Les champs à motifs doivent avoir des noms uniques dans l'objet conteneur.
Afin de préserver la capacité d'aller-retour entre les formats YAML et JSON, YAML version 1.2 est recommandé avec quelques contraintes supplémentaires:
- Les balises doivent être limitées à celles autorisées par l'ensemble de règles du schéma JSON.
- Les clés utilisées dans les cartes YAML DOIVENT être limitées à une chaîne scalaire, telle que définie par le jeu de règles du schéma YAML Failsafe.
En savoir plus
Description d’un document OpenAPI
Lorsque vous utilisez la spécification OpenAPI pour désigner votre API, vous pouvez entre autres : générer une documentation interactive, générer le code de la documentation, client et serveur. Cela est possible à travers de nombreux projets open source développés autour de la spécification OpenAPI.
Les langages supportés pour designer une API sont JSON et YAML. La spécification définit plusieurs étiquettes qui vont permettre entre autres de :
- définir les informations générales sur vos API : description, termes d’utilisation, licence, contact, etc. ;
- fournir la liste des services qui seront offerts, avec pour chacun, comment les appeler et la structure de la réponse qui est retournée ;
- définir le chemin pour consommer votre API ;
- etc.
Une fois que vous maitrisez le langage JSON ou YAML et que vous comprenez la structure d’un document OpenAPI, avec un simple éditeur de texte, vous êtes en mesure de désigner votre API.
Ci-dessous la structure d’un document YAML OpenAPI :
| Code YAML : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 | swagger: '2.0' info: version: Version de votre API title: Nom description: Description de l'API termsOfService: Termes d'utilisation contact: name: Nom personne de contact url: Site Web email: Adesse mail license: name: Nom de la licence url: Site Web ou tenir les informations sur la licence basePath: "/" paths: "Chemin de la l'API": get: tags: - Nom du Tag summary: Resumé de la méthode qui est exposée description: Description de la méthode exposée operationId: Nom de la méthode exposée consumes: [] produces: - application/json responses: '200': description: Description de la réponse schema: "$ref": "#/definitions/ExempleDefinition" definitions: ExempleDefinition: type: sttring |
Exemple de document pour une API Customers
Supposons que je souhaite mettre en place une API Customers. Cette API dispose d’une méthode Get permettant de retourner un Customer à partir de son ID. Ci-dessous la définition d’un Customer :
| Code C# : | Sélectionner tout |
1 2 3 4 5 6 7 | public class Customer { public int Id { get; set; } public string FirstName { get; set; } public string LastName { get; set; } public string EMail { get; set; } } |
Le document OpenAPI pour notre API au format JSON est le suivant :
| Code json : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 | { "swagger": "2.0", "info": { "version": "v2", "title": "SwaggerDemo API", "description": "Customers API to demo Swagger", "termsOfService": "None", "contact": { "name": "Hinault Romaric", "url": "http://rdonfack.developpez.com/", "email": "hinault@monsite.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org" } }, "basePath": "/", "paths": { "/api/Customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Retourne un client spécifique à partir de son id", "description": "Je manque d'imagination", "operationId": "ApiCustomersByIdGet", "consumes": [], "produces": [ "application/json" ], "parameters": [ { "name": "id", "in": "path", "description": "id du client à retourner", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "client sélectionné", "schema": { "$ref": "#/definitions/Customer" } } } } } }, "definitions": { "Customer": { "type": "object", "properties": { "id": { "format": "int32", "type": "integer" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "eMail": { "type": "string" } } } } } |
Et le document YAML est le suivant :
| Code YAML : | Sélectionner tout |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | swagger: '2.0' info: version: v2 title: SwaggerDemo API description: Customers API to demo Swagger termsOfService: None contact: name: Hinault Romaric url: http://rdonfack.developpez.com/ email: hinault@monsite.com license: name: Apache 2.0 url: http://www.apache.org basePath: "/" paths: "/api/Customers/{id}": get: tags: - Customers summary: Retourne un client spécifique à partir de son id description: Je manque d'imagination operationId: ApiCustomersByIdGet consumes: [] produces: - application/json parameters: - name: id in: path description: id du client à retourner required: true type: integer format: int32 responses: '200': description: client sélectionné schema: "$ref": "#/definitions/Customer" definitions: Customer: type: object properties: id: format: int32 type: integer firstName: type: string lastName: type: string eMail: type: string |
Source : note de version
Voir aussi :
Comprendre la spécification OpenAPI (Swagger) et apprendre à utiliser Swagger Editor, par Hinault Romaric