IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)

Vous êtes nouveau sur Developpez.com ? Créez votre compte ou connectez-vous afin de pouvoir participer !

Vous devez avoir un compte Developpez.com et être connecté pour pouvoir participer aux discussions.

Vous n'avez pas encore de compte Developpez.com ? Créez-en un en quelques instants, c'est entièrement gratuit !

Si vous disposez déjà d'un compte et qu'il est bien activé, connectez-vous à l'aide du formulaire ci-dessous.

Identifiez-vous
Identifiant
Mot de passe
Mot de passe oublié ?
Créer un compte

L'inscription est gratuite et ne vous prendra que quelques instants !

Je m'inscris !

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

Le , par Stéphane le calme

69PARTAGES

9  0 
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

Une erreur dans cette actualité ? Signalez-nous-la !