Discussion :

[Stéphane le calme]

L'Open API Initiative annonce la disponibilité de l'Open API Specification version 3.0.3,
OAS définit une description d'interface standard indépendante du langage de programmation pour les API REST

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 - Visualiser dans une fenêtre à part

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 - Visualiser dans une fenêtre à part

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 - Visualiser dans une fenêtre à part

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 - Visualiser dans une fenêtre à part

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