Formation documentation d'API avec Swagger

Leçon 1 • Aperçu 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 apprenant dispose d'un environnement fonctionnel avant d'écrire une spécification.

Leçon 3 • Ce que sont les API et comment elles fonctionnent

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 l'éditeur Swagger et les validateurs CLI pour vérifier l'exactitude des spécifications. Les apprenants corrigent de vraies erreurs de validation et comprennent les retours 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. Empêche les erreurs de formatage qui cassent les analyseurs de spécifications.

Leçon 3 • Structure d'un document OpenAPI

Décompose les champs de premier niveau : openapi, info, servers, paths et components. Les apprenants 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

Présente 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 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 de domaine réalistes tels que les utilisateurs, les commandes et les produits. Renforce les décisions de modélisation par des exercices pratiques et complets.

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 apprenants 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 apprenants écrivent des schémas qui rejettent les charges utiles invalides au niveau de la spécification.

Leçon 1 • Documentation des flux d'authentification

Explique comment documenter les points de terminaison d'acquisition, de rafraîchissement et de révocation de 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 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 apprenants é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 apprenants documentent des API à sécurité mixte où certains points de terminaison sont publics et d'autres 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 apprenants utilisent l'éditeur efficacement pour écrire et déboguer des spécifications.

Leçon 2 • Personnalisation de la marque et du style

Applique des CSS personnalisés et l'injection de logo pour aligner Swagger UI sur les directives de la marque. Les apprenants livrent un portail de documentation qui a un aspect professionnel.

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 apprenants 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 apprenants 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 apprenants documentent les API pilotées par les événements aux côtés des 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 apprenants migrent les spécifications 3.0 existantes pour tirer parti des nouvelles capacités.

Leçon 3 • Extensions de spécification

Présente les champs d'extension x- pour ajouter des métadonnées spécifiques au fournisseur aux spécifications. Les apprenants étendent OpenAPI sans casser la compatibilité des outils standard.

Leçon 4 • Gestion du versionnage dans les spécifications

Couvre les stratégies de versionnage par URL, en-tête et type de contenu dans les documents OpenAPI. Les apprenants 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 apprenants 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 apprenants débloquent les équipes frontend avant que l'implémentation backend ne soit terminée.

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

Explique comment générer des clients TypeScript, Python et Java à l'aide d'OpenAPI Generator. Les apprenants produisent des bibliothèques clientes fonctionnelles directement à partir de leurs spécifications.

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

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

Leçon 1 • Contrôle de version pour les spécifications

Applique les flux de travail Git (branches, tags et pull requests) aux fichiers OpenAPI. Les apprenants gèrent l'historique des spécifications avec la même rigueur que pour le 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 apprenants 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 apprenants éliminent les étapes manuelles de documentation qui introduisent de la dérive 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 apprenants choisissent l'approche appropriée en fonction de la structure de l'équipe et de la phase du projet.