Aller au contenu

Documentation d'un API avec OpenAPI

La documentation de l'api est une étape essentielle qu'il ne faut pas négliger. Vous devez toujours garder à l'esprit que votre API peut être destiné à être utilisé par d'autres utilisateurs et la documentation va indiquer la marche à suivre.

Votre documentation doit absolument comporter les éléments suivants :

  • Une liste de toutes les routes (endpoint) de votre api avec une description de leur utilité.
  • Les informations d'authentification s'il y a lieu.
  • Pour chaque route, les paramètres à ajouter à la requête.
  • Pour chaque route, toutes les réponses possibles et les valeurs retournées (code de status, données retournées)

Note

Nous allons utiliser la norme OpenAPI pour rédiger la documentation et le module Swagger UI Express pour le rendu visuel.

Installation

Installez le module Swagger UI Express avec npm

npm install swagger-ui-express

Dans le répertoire ./src/config/ créez un fichier JSON qui va contenir votre documentation. Pour l'instant copiez le contenu qui suit, on va voir la composition du fichier en détail plus loin.

./src/config/documentation.json
1
2
3
4
5
6
7
{
    "openapi": "3.1.0",
    "info":{
        "title": "Démo API",
        "version": "1.0.0"
    }
}

Dans le fichier de démarrage de votre application, ajoutez les lignes de codes suivantes (en surligné)

./index.js
 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
const express = require('express');
const dotenv = require('dotenv');
// Importation du module swagger-ui-express
const swaggerUi = require('swagger-ui-express');
// Le fichier de documentation JSON, ajustez selon votre projet
const swaggerDocument = require('./src/config/documentation.json');

// Options le l'interface, changez le titre "Demo API" pour le nom de votre projet 
const swaggerOptions = {
    customCss: '.swagger-ui .topbar { display: none }',
    customSiteTitle: "Demo API"
};

const app = express();
dotenv.config();

// Middleware
app.use(express.json());

// Routes
// La route à utiliser pour accéder au rendu visuel de la documentation
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, swaggerOptions));

app.listen(process.env.PORT || 3000, () => {
    console.log(`Le serveur tourne sur le port ${process.env.PORT}`);
});

Maintenant lancez votre application et accédez à la route que vous avez définie (/api/docs si vous avez utilisé le code plus haut). Vous devriez avoir ce résultat.

doc01.png

Résultat de la route /api/docs/

Composition du fichier de documentation

Le fichier JSON sera composé de plusieurs sections, certaines requises et d'autres optionnelles.

À la première ligne, ajouté la clé openapi avec la version d'OpenAPI que vous utilisez. Vous pouvez utiliser la version 3.1.0

documentation.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "openapi" : "3.1.0",
    "info" : { objet info },
    "servers" : [ objet server ],
    "paths" : {
        "route1" : { "method" : objet path }
    },
    "components" : {
        "schemas": {
            "nom_schema" : { objet schema }
        }
    }
}

info

L'information générale au sujet de votre api.

documentation.json
{
    "info" : {
        "title": "Titre de votre API [REQUIS]",
        "summary": "Une courte description de ce que fait votre API",
        "description": "Une description plus détaillé de ce que fait votre API",
        "contact": {
            "name": "API Support",
            "url": "https://www.example.com/support",
            "email": "support@example.com"
        },
        "version": "1.0.1 [REQUIS - Version de votre API]"
    }
}

servers

Un tableau d'objets serveurs qui indique où on peut exécuter l'api.

documentation.json
{
    "servers": [
        {
            "url": "http://api.profs.ca",
            "description": "Serveur en ligne"
        },
        {
            "url": "http://127.0.0.1:3000/",
            "description": "Serveur de développement"
        }
    ]
}

Manuel

https://swagger.io/specification/#server-object

paths

Une liste d'objets path qui détaillent les routes de votre api.

documentation.json
{
    "paths" : {
        "route1" : { objet path },
        "route2" : { objet path },
    }
}

Objet path

C'est avec l'objet path qu'on va détailler les routes. On va avoir une clé par route, même si elle est utilisée par plus d'une méthode http. Par exemple si j'ai une route GET /api/salutations et POST /api/salutations je vais ne faire qu'une entrée. Chaque méthode va être définie plus loin.

documentation.json
{
    "paths" : {
        "/api/salutations/liste" : {
            "get": {
                "description": "Retourne la liste de toutes les salutations",
                "summary": "Liste des salutations",
                "tags": [ "Salutions" ],
                "parameters": [ { objet parameter } ],
                "responses": {
                    "200": { response object }
                }
            },
            "post": {
                ...
            }
        }
    }
}

On ne fera pas l'énumération de toutes les options pour détailler une route, à l'essentiel vous devez avoir

  • Une description et un tags
  • La liste des paramètres requis
  • Toutes les réponses possibles detaillées

Pour plus d'information je vous invite à consulter la documentation

Manuel

components

Une section qui peut contenir une variété d'information, nous allons y définir nos modèles (avec un objet schema).

documentation.json
 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
{
    "components" : {
        "schemas": {
            "professeur" : {
                    "type": "object",
                    "required": [
                        "nom"
                    ],
                    "properties": {
                        "nom": {
                            "type": "string"
                        },
                        "prenom": {
                            "type": "string"
                        },
                        "age": {
                            "type": "integer",
                            "format": "int32",
                            "minimum": 0
                        }
                    }
            }
        }
    }
}

Manuel

Mediagraphie