diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index feb7f13..ec62b28 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -264,7 +264,9 @@
 ##### post.operationId
 
 Chaque service doit avoir un identifiant unique (ça permet d'avoir des liens
-uniques dans OpenAPI, et de nommer les requêtes dans `examples.http`).
+uniques dans OpenAPI, et de nommer les requêtes dans `examples.http`).  
+Lorsque l'identifiant n'est pas unique, le lien vers l'OpenAPI qui est fourni
+dans ObjectTDM est cassé !
 
 La convention pour construire cet identifiant est de partir du chemin du fichier
 `.ini`, de supprimer le `.ini`, et de remplacer chaque `/` par un `-`; il faut
@@ -273,8 +275,91 @@
 
 Ainsi, `terms-extraction/v1/teeft/en.ini` se traduit en `post-v1-teeft-en`.
 
+```ini
+post.operationId = post-v1-teeft-en
+```
+
+##### post.summary
+
+Description courte de la route, qui apparaît à droite de la route avant d'être
+dépliée dans OpenAPI.
+
+![Résumé d'une route dans OpenAPI](images/openapi-summary.png)
+
+##### post.description
+
+Description longue de la route, qui apparaît une fois que la route a été dépliée
+dans OpenAPI.
+
+![Description d'une route dans OpenAPI](images/openapi-description.png)
+
+On peut y employer MarkDown:
+
+```ini
+post.description = Traitement qui prend un objet JSON content un `id` et une `value` (contenant une année de publication, `year`, et une adresse `address`) et renvoie un `id` et une `value` (un tableau d'identifiants RNSR).
+```
+
+> **Remarque**: la colorisation syntaxique des éditeurs pour les `.ini` est
+> parfois abusée par le contenu des métadonnées (par exemple, dans ce cas, une
+> apostrophe seule est considérée comme un début de chaîne de caractères, non
+> fermée).  
+> Il n'y a pas à s'inquiéter, puisque cette syntaxe est bien comprise par le
+> serveur ezs, qui la transforme en un JSON compréhensible par Swagger (le
+> moteur d'OpenAPI).
+
+##### post.tags
+
+Les *tags* permettent de ranger les routes par sujet dans la page de présentation de l'instance sur OpenAPI.  
+
+![Les tags de l'instance `affiliations-tools` sur OpenAPI](images/openapi-at-tags.png)
+
+Le champ `post.tags` est un tableau, il nécessite donc d'utiliser un indice:
+
+```ini
+post.tags.0 = rnsr
+```
+
+On peut apposer plusieurs tags à une route, mais il reste encore à harmoniser
+les manières de faire pour tous les services web.
+
+Pour fonctionner, un tag doit être déclaré dans le fichier `swagger.json` qui se
+trouve à la racine de l'instance.  
+Ce fichier ne contient **que** les informations à ajouter au fichier généré
+automatiquement par le serveur ezs (et qui est exposé à sa racine).  
+
+C'est le champ `tags.*.name` du `swagger.json` qui doit correspondre au champ
+`post.tags.n`. Il sert d'identifiant.
+
+Exemple:
+
+```json
+{
+  "info": {
+    "version": "1.1.2"
+  },
+  "tags": [
+    {
+      "name": "rnsr",
+      "description": "RNSR",
+      "externalDocs": {
+        "description": "Plus de documentation",
+        "url": "https://gitbucket.inist.fr/tdm/web-services/tree/master/affiliations-tools#v1%2frnsr%2fcsv"
+      }
+    }, {
+      "name": "adresses",
+      "description": "Adresses",
+      "externalDocs": {
+        "description": "Plus de documentation",
+        "url": "https://gitbucket.inist.fr/tdm/web-services/tree/master/affiliations-tools#v1%2faddresses%2fparse"
+      }
+    }
+  ]
+}  
+```
+
 À CONTINUER...
-Avec les métadonnées de base: description, summary, tags...  
+Avec les métadonnées de base: post.responses.default.description, responses.default.content.application/json.schema.$ref, post.requestBody.required/content ...  
+validation swagger
 Modèle de base en ezs pur / avec python. À COMPLÉTER
 
 ### Python