OpenAPI 3.0 - Article

01/06/2024 - 12:50:56

10'27"

Introduction

TRQL Radio est bourré de services : passage au prochain morceau, passage d'un jingle, saut "quantique" dans le catalogue de musique, passage d'une locomotive, passage d'une annonce de sponsoring, passage des tops horaire, liste d'artistes correspondant à des critères spécifiques, météo, recettes de cuisine, géolocalisation et points d'intérêt aux coordonnées courantes, liste des anniversaires de naissance et de décès d'artistes, today in history, nouvelles du jour, devises par rapport à l'euro, cotation des cryptos, faillites par pays, index de corruption, notation attribuée par les agences de notation par pays, PIB par pays, … Nous avons plus de 200 services qui sont définis pour faire tourner la radio. Les services sont utilisés partout !

Objectif de cet article

Au terme de cet article vous devriez savoir comment utiliser l'éditeur Swagger pour développer vos services et microservices. Nous allons nous créer un compte gratuit et bénéficier des outils qui sont mis à notre disposition pour créer nos services et microservices. Il n'est pas indispensable d'utiliser Swagger pour développer nos services : n'importe quel éditeur de texte fera l'affaire, mais cela nous facilitera la tâche.

Swagger vs. OpenAPI 3.0

Smartbear est la société derrière Swagger; Swagger est l'un de leurs produits, un produit qui a eu un succès énorme de telle sorte qu'il est devenu un consortium sous le nom de OpenAPI.

Swagger c'est l'ancêtre de OpenAPI.

S'inscrire sur Swagger

Il suffit de vous rendre sur la page Swaggerhub et de demander à créer un compte gratuit :

Fig. 1 - Swaggerhub: Create Free Account

Fig. 2 - Swaggerhub: Create your account

Fig. 4 - Swaggerhub: Give some details and click on "Start trial"

Fig. 5 - Swaggerhub: Entrez le code à 5 chiffres que vous avez reçu par email

Pour finalement aboutir à …

Fig. 6 - Swaggerhub: Create a new API — Build Your Organization — Import an API

Créer sa première API

Ensuite, choisissez "Create a new API" (premier pavé) pour arriver à la page suivante :

Fig. 7 - Swaggerhub: Create a new API, choisissez ce qui convient et appuyez sur le bouton "Create API"

Dans notre cas, j'ai donné le nom "TRQLEconomics" comme nom de cette API. J'ai choisi d'utiliser la dernière spécification en date (3.1x). J'ai décidé de ne pas prendre de modèle (template --- None ---). La version de cette API est son tout début (version 0.0.1); j'ai fourni un titre, une description et ai indiqué que cettte API était publique. J'ai ensuite appuyé sur le bouton [ CREATE API ] …

Fig. 8 - Swaggerhub: nos premiers pas dans la création de notre première API

À partir d'ici, on se trouve dans l'éditeur YAML de Swaggerhub : à gauche, l'éditeur, à droite la traduction UI de ce qui est mentionné dans l'éditeur. Toute modification dans l'éditeur déclenche la modification de la partie droite.

Embryon d'API

Avec la Fig. 8 nous avons notre tout début d'API, juste les infos liées à l'objet info de OpenAPI. En voici le YAML :

openapi: 3.1.0
info:
  version: 0.0.1
  title: TRQL Radio economics-related services
  description: First version of the TRQLEconomics API featuring 3 services
paths: {}

C'est un YAML minimal que nous allons compléter gentiment. Nous allons commencer par les infos de contact, de licence et les conditions d'utilisation.

Contact, licence et conditions d'utilisation

Il suffit d'aller dans l'éditeur et de positionner le curseur là où vous souhaitez ajouter ces infos. Ensuite, appuyez sur Ctrl-space pour disposer d'une liste de champs possibles :

Selon la spécification de OpenAPI 3.0, l'objet contact dispose des propriétés suivantes :

name: (string) Le nom d'identification de la personne ou de l'organisation de contact.
url: (string) L'URL pointant vers les informations de contact. Doit être au format URL.
email: (string) L'adresse électronique de la personne/organisation de contact. Doit être au format d'une adresse électronique.

On va se contenter de l'adresse email : pb@latosensu.be

Fig. 10 - Swaggerhub: ajout de la licence

Fig. 11 - Swaggerhub: ajout des conditions d'utilisation

Notre YAML devient :

openapi: 3.1.0
info:
  version: 0.0.1
  title: TRQL Radio economics-related services
  description: First version of the TRQLEconomics API featuring 3 services
  contact:
    email: pb@latosensu.be
  license:
      name: CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
      url: https://creativecommons.org/licenses/by-sa/4.0/
  termsOfService: https://www.trql.fm/tos/
paths: {}

Au passage, focalisons-nous sur la partie droite de l'écran pour constater que les informations ont été mises à jour :

Fig. 12 - Swaggerhub: infos mises à jour

Ceci conclut la partie info de notre document OpenAPI.

Serveur

La spécification OpenAPI prévoit un tableau d'objets "serveur". Il est habituel de spécifier trois serveurs différents, un pour le développement, l'autre pour l'acceptance (ou staging) et enfin un serveur de production. Chez TRQL Radio, nous nous servons d'un seul serveur — celui de production — si bien qu'ici je ne vais mentionner QUE ce serveur. Dans votre cas, vous en aurez probablement plus qu'un.

L'info reprise ici sert à OpenAPI afin de générer les appels (requêtes) de manière correcte et aussi d'éviter de répéter l'URL à de multiples reprises.

Notez néanmoins que cet objet est optionnel d'après la spec. En voici la doc : Server Object.

url: (string) REQUIS. URL de l'hôte cible. Cette URL prend en charge les variables de serveur et PEUT être relative, pour indiquer que l'emplacement de l'hôte est relatif à l'emplacement où le document OpenAPI est servi. Des substitutions de variables seront effectuées lorsqu'une variable est nommée entre {acccolades}.
description (string) Chaîne facultative décrivant l'hôte désigné par l'URL. La syntaxe CommonMark peut être utilisée pour des représentations textuelles riches.
variables map (map) Une correspondance entre le nom d'une variable et sa valeur. La valeur est utilisée pour la substitution dans le modèle d'URL du serveur.

YAML :

openapi: 3.1.0
info:
  version: 0.0.1
  title: TRQL Radio economics-related services
  description: First version of the TRQLEconomics API featuring 3 services
  contact:
    email: pb@latosensu.be
  license:
      name: CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
      url: https://creativecommons.org/licenses/by-sa/4.0/
  termsOfService: https://www.trql.fm/tos/
servers:
  - url: https://www.trql.fm
    description: Production Server
paths: {}

Nous reviendrons sur l'URL du serveur un peu plus tard.

Requêtes et réponses

Avec les requêtes et les réponses, nous sommes au cœur du sujet. Nous allons devoir gérer le paths objects !

Cet objet contient LE ou LES chemins d'accès relatifs aux différents endpoints de vos services et à leurs opérations. Le chemin est ajouté à l'URL de l'objet serveur afin de construire l'URL complète. L'objet paths est un tableau d'objets path !

Voici le tableau récapitulatif de cet objet :

Field Name	Type	Description
$ref	`string`	Permet de disposer d'une définition externe (utilisation du "`$`") pour ce path. La structure référencée doit l'être dans le format d'un objet Path. S'il y a conflit entre la définition référencée et ce qui est attendu, le comportement est indéfini.
summary	`string`	Un résumé facultatif, sous forme de chaîne, destiné à s'appliquer à toutes les opérations de ce path.
description	`string`	Une description facultative, sous forme de chaîne, destinée à s'appliquer à toutes les opérations ce path. La syntaxe CommonMark peut être utilisée pour des représentations textuelles riches.
get	`Operation Object`	Définition d'une opération GET pour ce path.
put	`Operation Object`	Définition d'une opération PUT pour ce path.
post	`Operation Object`	Définition d'une opération POST pour ce path.
delete	`Operation Object`	Définition d'une opération DELETE pour ce path.
options	`Operation Object`	Définition d'une opération OPTIONS pour ce path.
head	`Operation Object`	Définition d'une opération HEAD pour ce path.
patch	`Operation Object`	Définition d'une opération PATCH pour ce path.
trace	`Operation Object`	Définition d'une opération TRACE pour ce path.
servers	`Server Object`	Un tableau `server` alternatif pour servir toutes les opérations dans ce path
parameters	`Parameter Object` \| `Reference Object`	Une liste de paramètres applicables pour toutes les opérations décrites pour ce path. Ces paramètres peuvent être redéfinis pour chaque opération, mais ne peuvent être éliminés. La liste ne PEUT PAS inclure de doublons. Un paramètre unique `parameter` est défini par une combinaison formée d'un nom (`name`) et d'une destination (`location`). La liste peut utiliser un `Reference Object` pour être couplée aux paramètres qui sont définis dans les composants et paramètres de l'objet OpenAPI.

Dans l'état actuel de notre document OpenAPI, nous avons défini l'objet "paths" comme tableau vide. Nous avons dû nous résoudre à ce stratégème car la spécification OpenAPI fait de cet objet un élement obligatoire :

openapi: 3.1.0
info:
  version: 0.0.1
  title: TRQL Radio economics-related services
  description: First version of the TRQLEconomics API featuring 3 services
  contact:
    email: pb@latosensu.be
  license:
      name: CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
      url: https://creativecommons.org/licenses/by-sa/4.0/
  termsOfService: https://www.trql.fm/tos/
servers:
  - url: https://www.trql.fm
    description: Production Server
paths: {}

Ajouter le service est simple et je ne vais pas en détailler tous les élements, surtout pas d'options plus complexes. Je vais tout simplement modifier le YAML directement dans l'éditeur:

openapi: 3.1.0
info:
  version: 0.0.1
  title: TRQL Radio economics-related services
  description: First version of the TRQLEconomics API featuring 3 services
  contact:
    email: pb@latosensu.be
  license:
      name: CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
      url: https://creativecommons.org/licenses/by-sa/4.0/
  termsOfService: https://www.trql.fm/tos/
servers:
  - url: http://www.trql.fm
    description: Production Server
paths:
  /vaesoli!/?bankruptcies:
    get:
      responses:
        '200':
        description: List of bankruptcies per country

J'ai donc spécifié le endpoint du service: /vaesoli!/?bankruptcies.

J'ai indiqué qu'il s'agisssait d'une requête de type GET en http.

J'ai indiqué un seul type de réponse: 200 (OK)

J'ai donné une description pour ce type de réponse.

J'ai gardé tout cela au strict minimum à des fins pédagogiques

Voici une autre version de notre YAML, une version que je préfère. La différence majeure se situe sur l'URL du serveur et la manière de spécifier les services :

openapi: 3.1.0
info:
  version: 0.0.1
  title: TRQL Radio economics-related services
  description: First version of the TRQLEconomics API featuring 3 services
  contact:
    email: pb@latosensu.be
  license:
      name: CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
      url: https://creativecommons.org/licenses/by-sa/4.0/
  termsOfService: https://www.trql.fm/tos/

servers:
  - url: http://www.trql.fm/vaesoli!
    description: Production Server
paths:
  /?bankruptcies:
    get:
      responses:
        '200':
          description: List of bankruptcies per country

Notez également que j'ai éliminé l'appel du https (je l'ai modifié en http) pour éviter ce genre de désagrément :

Fig. 14 - Swaggerhub: problème de certificat

Conclusion

Nous avons créé notre première API avec un tout premier service. Dans un article à venir, nous ajouterons les deux autres services de notre API, corruption et currencies avant d'ajouter un quatrième service, mercator qui, lui nécessite l'envoi de paramètres !

À très bientôt et, surtout, pas de complication !

OpenAPI 3.0 – Partie 2 : Utiliser Swagger