Formation en 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, dont OpenAPI, RAML et API Blueprint. Positionne OpenAPI comme la norme dominante de l'industrie pour le reste du cours.

Leçon 2 • Configuration de ton environnement de documentation

Guide les apprenants dans l'installation des outils et la configuration d'un espace de travail local. Assure que chaque étudiant dispose d'un environnement fonctionnel avant de rédiger 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 ta 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. Prévention des erreurs de formatage qui brisent 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 de base 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 de schéma ultérieur.

Leçon 2 • Documentation de modèles de données du monde réel

Applique les compétences en matière de schéma à 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 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 appliquent 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

Explique la documentation des points de terminaison d'acquisition, d'actualisation et de révocation de jetons. Assure 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 de codage. Établit un lien entre la sélection du type de contenu et la configuration correcte du schéma et du codage.

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 protégés.

Leçon 1 • Plongée en profondeur 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 rédiger et déboguer des spécifications.

Leçon 2 • Image de marque et style personnalisé

Applique du CSS personnalisé et l'injection de logo pour aligner Swagger UI sur les directives de marque. Les étudiants livrent un portail de documentation qui a l'air professionnellement soigné.

Leçon 3 • Test des API via Swagger UI

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

Leçon 4 • Déploiement de Swagger UI

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

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 profiter 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 étudiants étendent OpenAPI sans rompre la compatibilité des outils standard.

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

Couvre les stratégies de gestion de version 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 un développement parallèle. Les étudiants débloquent les équipes frontend avant la fin de l'implémentation backend.

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

Explique 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 • Contrôle de version pour les spécifications

Applique les workflows Git de branchement, d'étiquetage et de demande de tirage aux fichiers OpenAPI. Les étudiants gèrent l'historique des spécifications avec la même rigueur que le code source.

Leçon 2 • Gouvernance et guides de style

Crée des règles organisationnelles pour nommer, formater et structurer les fichiers OpenAPI. Les étudiants appliquent la cohérence entre plusieurs API et équipes à l'aide de 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 validation. Les étudiants éliminent les étapes manuelles de documentation qui introduisent des dérives et des erreurs.

Leçon 4 • Approches spécification d'abord vs. code d'abord

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