Cours de documentation d'API avec Swagger

Leçon 1 • Présentation des normes de documentation

Présente les principaux formats de spécification d'API, notamment OpenAPI, RAML et API Blueprint. Positionne OpenAPI comme le standard dominant du secteur pour le reste du cours.

Leçon 2 • Configuration de votre environnement de documentation

Guide les apprenants dans l'installation des outils et la configuration d'un espace de travail local. S'assure que chaque étudiant dispose d'un environnement fonctionnel avant d'écrire une spécification.

Leçon 3 • Que sont les API et comment fonctionnent-elles ?

Couvre REST, les méthodes HTTP, les requêtes et les réponses à un niveau conceptuel. Établit le vocabulaire technique nécessaire tout au long du cours.

Leçon 1 • Validation de votre première spécification

Utilise Swagger Editor et les validateurs en ligne de commande pour vérifier l'exactitude de la spécification. Les étudiants corrigent de vraies erreurs de validation et comprennent les commentaires de l'analyseur.

Leçon 2 • YAML et JSON pour OpenAPI

Enseigne la syntaxe YAML, les règles d'indentation et les équivalents JSON utilisés dans les fichiers OpenAPI. Évite les erreurs de formatage qui interrompent les analyseurs de spécification.

Leçon 3 • Structure d'un document OpenAPI

Décompose les champs de premier niveau : openapi, info, servers, paths et components. Les étudiants comprennent comment chaque champ contribue à une spécification complète.

Leçon 4 • Description des réponses

Explique comment documenter les codes de réponse, les en-têtes et les schémas de corps. Établit un lien entre une documentation précise des réponses et une génération fiable de code client.

Leçon 1 • Concepts fondamentaux de JSON Schema

Introduit les types, les propriétés, les champs obligatoires et les contraintes dans JSON Schema. Fournit le vocabulaire de modélisation utilisé dans tout le travail ultérieur sur les schémas.

Leçon 2 • Documentation de modèles de données concrets

Applique les compétences en matière de schéma à des objets métier réalistes tels que les utilisateurs, les commandes et les produits. Renforce les décisions de modélisation par des exercices pratiques de bout en bout.

Leçon 3 • Composants réutilisables et références

Démontre le mot-clé $ref et la section components/schemas pour une documentation DRY. Les étudiants refactorisent les schémas en ligne en définitions partagées et réutilisables.

Leçon 4 • Mots-clés de contrainte et de validation

Couvre les contraintes numériques, de chaîne et de tableau qui imposent l'intégrité des données. Les étudiants écrivent des schémas qui rejettent les charges utiles invalides au niveau de la spécification.

Leçon 1 • Documentation des flux d'authentification

Parcourt la documentation des points de terminaison d'obtention, d'actualisation et de révocation des jetons. Garantit que les consommateurs comprennent l'ensemble du cycle de vie de l'authentification à partir de la seule spécification.

Leçon 2 • Corps de la requête et types de contenu

Documente les corps de requête JSON, de formulaire et multipart avec les détails d'encodage. Établit un lien entre la sélection du type de contenu et la configuration correcte du schéma et de l'encodage.

Leçon 3 • Types de paramètres en profondeur

Couvre les paramètres de chemin, de requête, d'en-tête et de cookie avec les règles de sérialisation. Les étudiants évitent les définitions de paramètres ambiguës qui confondent les consommateurs d'API.

Leçon 4 • Application de la sécurité aux opérations

Montre comment attacher des exigences de sécurité globalement et par opération. Les étudiants documentent des API à sécurité mixte où certains points de terminaison sont publics et d'autres sont protégés.

Leçon 1 • Exploration approfondie de Swagger Editor

Explore les fonctionnalités de validation en temps réel, d'autocomplétion et d'aperçu de Swagger Editor. Les étudiants utilisent l'éditeur efficacement pour écrire et déboguer des spécifications.

Leçon 2 • Marque et personnalisation du style

Applique un CSS personnalisé et une injection de logo pour aligner Swagger UI sur les directives de la marque. Les étudiants livrent un portail de documentation à l'aspect professionnel soigné.

Leçon 3 • Test des API via Swagger UI

Utilise la fonctionnalité Try It Out pour exécuter des appels API en direct à partir de la documentation. Les étudiants vérifient que leur spécification reflète avec précision le comportement réel de l'API.

Leçon 4 • Déploiement de Swagger UI

Couvre les options de déploiement npm, CDN et Docker pour Swagger UI. Les étudiants hébergent un site de documentation fonctionnel à partir d'un environnement local ou cloud.

Leçon 1 • Callbacks et webhooks

Couvre les objets callback pour documenter les notifications push asynchrones et les webhooks. Les étudiants documentent les API événementielles parallèlement aux modèles traditionnels requête-réponse.

Leçon 2 • Nouvelles fonctionnalités d'OpenAPI 3.1

Met en évidence l'alignement complet avec JSON Schema, les webhooks et les changements de dialecte de schéma dans la version 3.1. Les étudiants migrent les spécifications 3.0 existantes pour tirer parti des nouvelles capacités.

Leçon 3 • Extensions de spécification

Introduit les champs d'extension x- pour ajouter des métadonnées spécifiques au fournisseur aux spécifications. Les étudiants étendent OpenAPI sans compromettre la compatibilité avec les outils standard.

Leçon 4 • Gestion des versions dans les spécifications

Couvre les stratégies de versionnement par URL, en-tête et type de contenu dans les documents OpenAPI. Les étudiants documentent plusieurs versions d'API sans dupliquer des fichiers de spécification entiers.

Leçon 1 • Introduction à la génération de code

Explique comment les générateurs analysent les spécifications OpenAPI pour produire du code spécifique à un langage. Les étudiants comprennent la relation entre la qualité de la spécification et la qualité du code généré.

Leçon 2 • Serveurs simulés à partir de spécifications

Génère des serveurs fictifs à l'aide de Prism et Stoplight pour permettre le développement parallèle. Les étudiants débloquent les équipes frontend avant que l'implémentation backend ne soit terminée.

Leçon 3 • Génération de SDK clients

Parcourt la génération de clients TypeScript, Python et Java à l'aide d'OpenAPI Generator. Les étudiants produisent des bibliothèques clientes fonctionnelles directement à partir de leurs spécifications.

Leçon 4 • Tests de contrat avec les spécifications

Utilise des outils comme Dredd et Schemathesis pour valider les API par rapport à leurs spécifications OpenAPI. Les étudiants détectent les violations de contrat avant qu'elles n'atteignent la production.

Leçon 1 • Gestion de versions pour les spécifications

Applique les workflows Git de branchement, d'étiquetage et de pull request aux fichiers OpenAPI. Les étudiants gèrent l'historique des spécifications avec la même rigueur appliquée au code source.

Leçon 2 • Gouvernance et guides de style

Crée des règles organisationnelles pour le nommage, le formatage et la structuration des fichiers OpenAPI. Les étudiants imposent la cohérence entre plusieurs API et équipes à l'aide d'un linting automatisé.

Leçon 3 • Automatisation des pipelines de documentation

Construit des pipelines CI/CD qui valident, génèrent et publient la documentation à chaque commit. Les étudiants éliminent les étapes de documentation manuelles qui introduisent des dérives et des erreurs.

Leçon 4 • Approches spec-first vs code-first

Compare la conception de la spécification avant le codage à la génération de spécifications à partir d'annotations. Les étudiants sélectionnent l'approche appropriée en fonction de la structure de l'équipe et de la phase du projet.