YAML dans le contexte de OpenAPI 3.0

31/05/2024 - 09:31:48

5'03"

Contexte — Mise en garde

Le sujet de cette page est de détailler l'utilisation que nous faisons de YAML dans le cadre de l'écriture de services et microservices de type REST (OpenAPI 3.0). Ce que nous en dirons est basé sur l'expérience que nous avons acquise en la matière, notamment au travers de l'écriture de NOS propres services.

Introduction

YAML signifie … YAML Ain't Markup Language. C'est donc un langage et ce langage est utilisé un peu partout, en particulier dans le monde DevOps, notamment pour écrire des fichiers de configuration (Docker, Kubernetes, Ansible, Promotheus, …). En vous rendant sur le site offciel de YAML, vous y trouverez d'entrée de jeu une liste impressionnante de packages YAML prêts à l'emploi pour votre langage de programmation favori.

YAML est un langage de sérialisation de données, tout comme le sont XML et JSON. C'est un langage qui transforme des structures (des imbrications, des juxtapositions, …) en une longue chaîne de caractères (sens du mot sérialisation).

Comme une chaîne de caractères peut être lue par différentes technologies on en déduit assez justement que YAML est un langage complètement agnostique de l'utilisation qui en sera faite mais aussi bien agnostique vis-à-vis du langage utilisé pour lire les chaînes YAML : il peut servir à des tas de choses et vous pouvez attaquer le YAML au départ de Java, PHP, Python, … ! Une fois de plus, rendez-vous sur la page d'accueil de YAML pour voir tous les langages pouvant offrir un support YAML.

La dernière version de YAML date de 2021. C'est la version 1.2. Vous en trouverez la spécification complète sur la page Revision 1.2.2 ^[1] .

Syntaxe YAML

Notions de base

Pour YAML, les lignes et l'indentation sont des éléments structurants du langage. Chaque ligne commence une nouvelle donnée tandis que l'indentaion marque la structure et l'imbrication (exactement comme nous le faisons avec des listes commençant par une puce ou un tiret quand nous écrivons).

Mon intention n'est pas de présenter ici l'entièreté de la syntaxe YAML ici — si c'est ce que vous cherchez, rendz-vous plutôt sur la page Revision 1.2.2 — mais de rassembler les éléments du langage nécessaires à écrire des services et microservices, et ce, dans l'objectif de se préparer à un autre article à venir consacré à OpenAPI 3.0.

Les types de données gérés par YAML

YAML gère des scalaires, des listes et des structures (données hiérarchisées).

Un scalaire est un type de données simple. C'est simple valeur pour une clé. La valeur du scalaire peut être un nombre, un booléen ou une chaîne de caractères. Ce mot, scalaire ne doit pas vous impressionner.

Un nombre, en YAML, peut être un entier ou un flottant. Il est possible d'exprimer les nombres par une notation décimale, par une notation hexadécimale, ou par une notation octale.

Caractères spéciaux

Les caractères spéciaux doivent être précédés d'un "\" pour être correctement interprétés. Par exemple, le ":", s'il doit être utilisé dans une description, doit être précédé du "\".

Liste de syntaxe de base

Racine
Une ligne qui commence par "---" indique un élément racine pour séparer de multiples notions. Chaque élément racine possède ses propres propriétés et structures.
Exemple:
```
---
# Component 1
---
# Component 2
```
Commentaire
Un commentaire est une ligne qui commence par "#" Exemple:
```
# Ceci est un commentaire
```
Propriété
Une propriété est une paire "clef:valeur"
Exemples:
```
service-name: bankruptcies
version: '1.17'
```
Propriété logique
Une propriété logique implique que la valeur soit libellée avec true|false ou yes|no ou on|off
Exemples:
```
deployed: true
deployed: "true"
deployed: No
deployed: off
```
Nombre entier
Exemple:
```
level: 100
```
Nombre entier octal
Exemple (100 en octal):
```
level: 0o144
```
Nombre entier hexadécimal
Exemple (100 en hexadécimal):
```
level: 0x64
```
Nombre flottant
Exemple:
```
level: 100.47
```
Propriété chaîne de caractères
Une chaîne de caractères ne doit pas être comprise entre guillemets
Exemples:
```
name: "Pat Boens"
name: 'Pat Boens'
name: Pat Boens
```
Propriété chaîne de caractères multi-lignes avec renvoi à la ligne
Exemple (les renvois à la ligne sont supportés):
```
name: | Mon nom long
sur plusieurs lignes
```
Propriété chaîne de caractères multi-lignes sans renvoi à la ligne
Exemple (les renvois à la ligne sont supprimés):
```
name: > Mon nom long
sur plusieurs lignes
rendus sur une seule
```
Liste de valeurs
Exemple:
```
items: [1,2,3,4]
```
Liste de valeurs (présentée avec des tirets)
Exemple (même signification que l'exemple précédent — attention, l'indentation doit être la même):
```
items:
  - 1
  - 2
  - 3
  - 4
```
Autre exemple:
```
items:
  - "one"
  - "two"
  - "three"
  - "four"
```

Structure
Exemple (attention à l'indentation):

microservices:
  - app: economics
    port: 5000
    version: 1.17

Cet exemple pourrait être écrit de la manière suivante en XML :

<microservices>
  <app>economics</app>
  <port>5000</port>
  <version>1.17</version>
</microservices>

En JSON, cela donne :

{
  "microservices": [
    {
      "app": "economics",
      "port": 5000,
      "version": 1.17
    }
  ]
}

Muni de cette syntaxe de base, vous êtes suffisamment armé pour écrire vos services et microservices en YAML … pourvu que vous sachiez exprimer cela suivant les règles de OpenAPI 3.0 ce qui est l'objet de cet autre article: OpenAPI 3.0.

Liens utiles

Notes de bas de page

^[1] … Version en cours au moment d'écrire cet article, soit au 30/05/2024 09:41:06

YAML,dans le contexte d'OpenAPI