Concevoir d’abord la spec et la simuler

Spec-first signifie que le document OpenAPI vient avant le code : on s’accorde sur l’API, on l’essaie avec un mock, puis on vérifie le vrai serveur par rapport au même document une fois qu’il existe. Dans ce tutoriel, vous ajoutez la spec de la boutique Alpenglow à un espace de travail, vous concevez un endpoint que la boutique n’a pas encore, vous servez les deux depuis un mock sur votre Mac et vous vérifiez les réponses de la vraie API par rapport à la spec.

• Durée : 20 minutes.
• Il vous faut : Echolot et un espace de travail, comme celui de Votre premier espace de travail ou un nouvel espace vide.
• Vous apprenez : la page Specs, le lint, les requêtes qui suivent une spec, les mocks et la vérification Spec OpenAPI.

1. Ajouter la specCopy Anchor Link

La boutique de démo publie sa spec à l’adresse https://demo.echolot.dev/openapi.yaml.

1. Enregistrez-la sur votre Mac. Dans Terminal :

   Copier le texte

   curl -o ~/Downloads/openapi.yaml https://demo.echolot.dev/openapi.yaml

   Ou ouvrez l’adresse dans Safari et choisissez Fichier › Enregistrer sous….

2. Dans la fenêtre de l’espace de travail, passez sur Specs (⌘3).

3. Choisissez Ajouter un fichier de spec… (sur la page vide, ou dans le menu + de la barre latérale) et sélectionnez openapi.yaml. Une copie va dans le dossier specs de l’espace de travail.

La spec s’ouvre dans l’éditeur Visuel : ses serveurs, ses endpoints regroupés par chemin ou par tag, et ses schémas. Le sélecteur de la barre d’outils permet de passer de Visuel à Code. Les deux modifient le même texte, et c’est le texte qui est enregistré.

2. Concevoir un endpoint que la boutique n’a pasCopy Anchor Link

La boutique veut une liste de ses magasins. Concevez-la avant que quiconque l’écrive.

1. Dans l’éditeur Visuel, choisissez Ajouter un endpoint.

2. Dans Nouvel endpoint, laissez Méthode sur GET, saisissez le chemin /stores, le résumé List stores et le tag Catalog. Cliquez sur Ajouter un endpoint. Echolot ajoute l’opération avec une réponse 200 comme point de départ.

3. Dans l’éditeur de l’endpoint, définissez ID de l’opération sur listStores.

4. Choisissez Afficher dans le code. Remplacez les responses de l’endpoint par un corps et un exemple :

   Copier le texte

         responses:
           '200':
             description: The shop's stores.
             content:
               application/json:
                 schema:
                   type: array
                   items:
                     type: object
                     required: [id, city]
                     properties:
                       id: { type: string }
                       city: { type: string }
                       address: { type: string }
                 example:
                   - { id: zrh, city: Zürich, address: Bahnhofstrasse 1 }
                   - { id: brn, city: Bern, address: Spitalgasse 4 }

Les modifications sont enregistrées au fur et à mesure, et ⌘Z les annule. Les modifications visuelles ne changent que les lignes de l’entrée que vous touchez, si bien que le reste du fichier, commentaires compris, reste tel que vous l’avez écrit. Plus de détails dans modifier des specs.

3. Linter la specCopy Anchor Link

Le bouton des problèmes de la barre d’outils affiche une coche verte et Aucun problème, ou un nombre d’erreurs et d’avertissements.

1. Cliquez dessus. La fenêtre Problèmes indique que le document respecte la spécification OpenAPI et que chaque référence se résout.
2. Cassez quelque chose pour voir un problème : dans Code, changez $ref: '#/components/schemas/Product' sur une ligne en '#/components/schemas/Produkt'. Le bouton devient rouge. Cliquez dessus et choisissez le problème : l’éditeur saute à sa ligne.
3. Annulez la modification (⌘Z).

Le même lint s’exécute en CI avec l’outil en ligne de commande. --strict échoue aussi sur les avertissements, et --hints ajoute des conseils comme les ID d’opération manquants :

echolot spec lint specs/openapi.yaml --strict

4. Créer des requêtes qui suivent la specCopy Anchor Link

1. Dans la barre d’outils Specs, choisissez Générer les requêtes. Un dossier Alpenglow demo shop apparaît sous Requêtes, avec un dossier par tag (Catalog, Auth, Orders) et une requête pour chaque endpoint, List stores compris.
2. Regardez Catalog › List products. Son URL est {{baseUrl}}/products. Son onglet Tests a déjà deux vérifications issues de la spec : État est égal à 200, et un JSON Schema du corps documenté.

Le dossier suit la spec. Quand la spec changera plus tard, le menu Requêtes de la barre d’outils Specs propose Vérifier les changements de « Alpenglow demo shop »… : il liste ce qui est nouveau, modifié et disparu dans la spec et l’applique sans écraser vos propres modifications des requêtes. Voir synchronisation OpenAPI.

Les requêtes générées commencent par {{baseUrl}} (rl en minuscules). Vous lui donnez une valeur dans les deux étapes suivantes.

5. Servir un mock de la specCopy Anchor Link

1. Passez sur Mocks (⌘4). Ouvrez le menu + et choisissez Mock de Alpenglow demo shop.
2. Cliquez sur Démarrer (⌘R). La barre d’outils affiche un point vert et l’adresse http://127.0.0.1:4010/v1 : le premier port libre à partir de 4010, et le chemin de base du serveur de la spec.
3. Cliquez sur Utiliser dans un environnement. Echolot crée un environnement Mock : Alpenglow demo shop dont {{baseUrl}} est l’adresse du mock, et le choisit.

La carte Réglages contient le Port du mock, Répondre aux autres appareils du réseau, un Délai avant chaque réponse, une part d’Échecs (des 500 injectés) et des Vérifications : Refuser les requêtes qui ne respectent pas la spec (400 avec les raisons). Le mock tourne tant que la fenêtre est ouverte.

6. Envoyer des requêtes au mockCopy Anchor Link

1. De retour dans Requêtes, envoyez Catalog › List stores. Le mock répond 200 avec les deux magasins de votre exemple. L’onglet En-têtes montre Server: Echolot mock.
2. Envoyez Catalog › List products. Le mock n’a pas d’exemple pour elle, il fabrique donc un corps à partir du schéma : la bonne forme avec des valeurs fictives. Les deux vérifications de la requête réussissent.
3. Dans les Paramètres de List products, ajoutez sort avec la valeur cheapest et envoyez. Le mock la refuse : 400 avec query “sort”: not one of the allowed values. La spec autorise name, price, -price et rating. Retirez le paramètre.
4. Dans Get a product, ajoutez l’en-tête Prefer: code=404 et envoyez. Le mock répond avec le problème 404 documenté à la place. Retirez l’en-tête.

Le JOURNAL de la page Mocks liste chaque requête à laquelle le mock a répondu, avec l’opération qui correspondait et l’éventuel problème. Dans la carte Réponses, vous pouvez faire répondre une opération avec un autre état ou exemple documenté pour chaque requête. Les routes JavaScript pour les réponses qui ont besoin d’un état se trouvent dans routes scriptées.

7. Vérifier la vraie API par rapport à la specCopy Anchor Link

1. Sur la page Environnements, ajoutez un environnement Demo avec une variable baseUrl définie sur https://demo.echolot.dev/v1, et choisissez-le dans l’en-tête de page.
2. Ouvrez List products, ouvrez Ajouter un test dans son onglet Tests et choisissez Spec OpenAPI. Il n’y a rien à renseigner : elle vérifie le corps par rapport au schéma que la spec documente pour l’état qui est revenu.
3. Envoyez-la. Les trois vérifications réussissent : la vraie boutique correspond à sa spec.
4. Envoyez List stores. La vraie boutique répond 404 : l’endpoint n’existe que dans la spec. C’est tout l’intérêt de spec-first : le mock vous permet de construire dessus dès maintenant.

Pour exécuter les mêmes vérifications en CI, exécutez le dossier avec echolot run et servez-y le mock avec echolot mock :

echolot mock specs/openapi.yaml --port 4010

Étapes suivantesCopy Anchor Link

• Specs à partir du trafic : écrivez une spec à partir de requêtes que vous envoyez déjà.
• Mocks : exemples enregistrés depuis l’historique, délais, échecs et partage sur le réseau.
• echolot spec : check fait échouer la CI quand un dossier est en retard sur sa spec.