Cours de documentation d'API avec Swagger

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

Passe en revue les principaux formats de spécification d'API, notamment OpenAPI, RAML et API Blueprint. Positionne OpenAPI comme la norme dominante 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. Garantit que chaque étudiant dispose d'un environnement fonctionnel avant de rédiger 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 les erreurs de validation réelles et comprennent les commentaires de l'analyseur syntaxique.

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 cassent les analyseurs de spécification.

Leçon 3 • Structure du 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. Relie une documentation précise des réponses à 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émas à 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

Illustre 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, sur les chaînes et sur les tableaux 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. Relie la sélection du type de contenu à la configuration correcte du schéma et de l'encodage.

Leçon 3 • Types de paramètres en détail

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 les 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 • Plongée approfondie dans 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 les spécifications.

Leçon 2 • Personnalisation de l'image de marque et du style

Applique des CSS personnalisées et l'injection de logo pour aligner Swagger UI sur la charte graphique. Les étudiants livrent un portail de documentation à l'aspect professionnel et soigné.

Leçon 3 • Test des API via Swagger UI

Utilise la fonctionnalité Try It Out pour exécuter des appels API en direct depuis 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 orientées événements aux côtés des modèles traditionnels de 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 casser la compatibilité avec les outils standard.

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

Couvre les stratégies de versioning 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 simulés à 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 que celle appliquée au code source.

Leçon 2 • Gouvernance et guides de style

Crée des règles organisationnelles pour la dénomination, le formatage et la structuration des fichiers OpenAPI. Les étudiants imposent la cohérence entre plusieurs API et équipes à l'aide du 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 manuelles de documentation 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.