Documenter les APIs avec Swagger (1/4) — Introduction

Dans cette série d’articles, je vais introduire les différents outils de Swagger. Swagger est un outil très pratique de documentation des APIs. Il permet de générer de la documentation “vivante”, permettant ainsi que la documentation soit toujours à jour, ce qui est très difficile à réaliser sans ce genre d’outil. Il permet également de générer du code automatiquement, permettant au développeur de se concentrer sur le coeur de son activité. Enfin, il repose sur un format de spécifications open source.

Cet article est donc décomposé en quatre parties :

La spécification OpenAPI (OAS — OpenAPI Specification) (https://www.openapis.org/) permet de découvrir les fonctionnalités d’un service sans avoir de détails sur le code utilisé pour implémenter l’API.

C’est une interface Open Source indépendante du langage utilisé pour créer l’API REST créée dans le cadre de Linux Foundation.

Le cas d’usage est qu’après avoir écrit la spécification OpenAPI, vous disposez d’une documentation interactive de l’API.

La spécification peut être écrite en YAML ou en JSON.

La spécification Swagger est disponible à l’adresse https://Swagger.io/specification.

Swagger permet de générer l’implémentation d’une API dans l’un des langages supportés à partir de sa spécification. De nombreux langages sont supportés.

Cette spécification peut être utilisée par de nombreux autres outils : Postman, API Gateway de AWS, etc …

Structure d’un fichier de spécification Swagger

Voici un exemple de spécification (fichier swagger.yaml) :

cat <<EOF> swagger.yaml
swagger: "2.0"
info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"
host: "0.0.0.0:8080"
basePath:
schemes: ["http"]
tags:
- name: "Contact"
paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"
produces:
- "application/json"
responses:
200:
schema:
\$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
\$ref: "#/definitions/ContactCreateRequest"
responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"
definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
\$ref: "#/definitions/ContactResponse"
EOF

La spécification correspondante est :

swagger: "2.0"
info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"
host: "0.0.0.0:8080"
schemes: ["http"]
tags:
- name: "Contact"
paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"
produces:
- "application/json"
responses:
200:
schema:
$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
$ref: "#/definitions/ContactCreateRequest"
responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"
definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
$ref: "#/definitions/ContactResponse"

Etudions la structure d’un fichier Swagger. Un fichier Swagger peut être au format JSON ou au format YAML. Il décrit donc les appels de l’API REST.

La version utilisée de Swagger :

swagger: "2.0"

Les métadonnées sur l’API :

info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"

L’adresse du serveur sur lequel l’API est hébergée :

host: "0.0.0.0:8080"

Le chemin de base de l’API, relatif à la valeur de host :

basePath:

Le protocole utilisé (HTTP ou HTTPS) :

schemes: "http"tags:
- name: "Contact"

Le chemin d’accès à l’API ou aux ressources :

paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"

Les types de média Internet utilisés :

consumes:
- "*/*"

Les types de média Internet générés :

produces:
- "application/json"

Le type de réponse pour l’opération :

responses:
200:
schema:
$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"

Les types de média Internet utilisés :

consumes:
- "application/json"

Les types de média Internet générés :

produces:
- "application/json"

Les détails de paramètre pour une opération :

parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
$ref: "#/definitions/ContactCreateRequest"

Le type de réponse pour l’opération :

responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"

Les types d’entité en entrée et en sortie pour les opérations sur les ressources de l’API :

definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
$ref: "#/definitions/ContactResponse"

Pour obtenir l’URL complète, Swagger concatène basePath et paths.

Pour plus d’informations, consultez l’adresse https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md.

La version utilisée de Swagger :

swagger: "2.0"

Les métadonnées sur l’API :

info:
description: "Specification for contacts"
version: "1.0.0"
title: "Contact contract"

L’adresse du serveur sur lequel l’API est hébergée :

host: "0.0.0.0:8080"

Le protocole utilisé (HTTP ou HTTPS) :

schemes: "http"tags:
- name: "Contact"

Le chemin d’accès à l’API ou aux ressources :

paths:
/contact:
get:
tags:
- "Contact"
summary: "Gets the list of contacts"
description: ""
operationId: "getContacts"

Les types de média Internet utilisés :

consumes:
- "*/*"

Les types de média Internet générés :

produces:
- "application/json"

Le type de réponse pour l’opération :

responses:
200:
schema:
$ref: "#/definitions/ListContactsResponse"
description: "List of contacts"
post:
tags:
- "Contact"
summary: "Creates a new contact"
operationId: "createContact"

Les types de média Internet utilisés :

consumes:
- "application/json"

Les types de média Internet générés :

produces:
- "application/json"

Les détails de paramètre pour une opération :

parameters:
- in: "body"
name: "Contact"
description: "The contact data"
required: true
schema:
$ref: "#/definitions/ContactCreateRequest"

Le type de réponse pour l’opération :

responses:
201:
description: "Contact creation succeeded"
400:
description: "Contact creation failed"

Les types d’entité en entrée et en sortie pour les opérations sur les ressources de l’API :

definitions:
ContactCreateRequest:
type: "object"
properties:
name:
type: "string"
ContactResponse:
type: "object"
properties:
id:
type: "integer"
name:
type: "string"
ListContactsResponse:
type: "array"
items:
$ref: "#/definitions/ContactResponse"

Dans cette première partie, vous avez compris les choses les plus importantes à savoir sur la spécification Swagger 2.0.

More articles on my blog http://www.DevOpsTestLab.com.

My DevOpsTestLab Youtube channel.

My LinkedIn profile: https://fr.linkedin.com/in/brunodelb

Written by

Interests in the full lifecycle: design, Agile Coaching, development, testing, DevOps, Cloud, Management 3.0, ITIL. It defines me.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store