API-documentatie met Swagger cursus

Les 1 • Overzicht van documentatiestandaarden

Onderzoekt de belangrijkste API-specificatieformaten, waaronder OpenAPI, RAML en API Blueprint. Positioneert OpenAPI als de dominante industriestandaard voor de rest van de cursus.

Les 2 • Je documentatieomgeving instellen

Begeleidt cursisten bij het installeren van tools en het configureren van een lokale werkruimte. Zorgt ervoor dat elke student een functionele omgeving heeft voordat hij een specificatie schrijft.

Les 3 • Wat API's zijn en hoe ze werken

Behandelt REST, HTTP-methoden, verzoeken en antwoorden op conceptueel niveau. Vestigt de technische woordenschat die gedurende de hele cursus nodig is.

Les 1 • Je eerste specificatie valideren

Gebruikt Swagger Editor en CLI-validators om de juistheid van de specificatie te controleren. Studenten repareren echte validatiefouten en begrijpen parserfeedback.

Les 2 • YAML en JSON voor OpenAPI

Leert YAML-syntax, inspringingsregels en JSON-equivalenten die worden gebruikt in OpenAPI-bestanden. Voorkomt opmaakfouten die specificatieparsers breken.

Les 3 • OpenAPI-documentstructuur

Breekt de velden op het hoogste niveau op: openapi, info, servers, paths en components. Studenten begrijpen hoe elk veld bijdraagt aan een volledige specificatie.

Les 4 • Antwoorden beschrijven

Legt uit hoe je antwoordcodes, headers en bodyschema's documenteert. Verbindt nauwkeurige antwoorddocumentatie met betrouwbare clientcodegeneratie.

Les 1 • Kernconcepten van JSON Schema

Introduceert typen, eigenschappen, verplichte velden en constraints in JSON Schema. Biedt de modelleringswoordenschat die in al het verdere schema-werk wordt gebruikt.

Les 2 • Realistische datamodellen documenteren

Past schemavaardigheden toe op realistische domeinobjecten zoals gebruikers, bestellingen en producten. Versterkt modelleringsbeslissingen door middel van praktische, end-to-end oefeningen.

Les 3 • Herbruikbare componenten en verwijzingen

Demonstreert het $ref-sleutelwoord en de componenten/schema's-sectie voor DRY-documentatie. Studenten herstructureren inline-schema's naar gedeelde, herbruikbare definities.

Les 4 • Constraints en validatiesleutelwoorden

Behandelt numerieke, string- en array-constraints die gegevensintegriteit afdwingen. Studenten schrijven schema's die ongeldige payloads op specificatieniveau afwijzen.

Les 1 • Authenticatiestromen documenteren

Loopt door het documenteren van token-acquisitie-, refresh- en revocation-endpoints. Zorgt ervoor dat consumenten de volledige authenticatielevenscyclus uit de specificatie alleen begrijpen.

Les 2 • Aanvraagbody en contenttypen

Documenteert JSON-, formulier- en multipart-aanvraagbodys met coderingsdetails. Verbindt contenttype-selectie met correcte schema- en coderingsconfiguratie.

Les 3 • Parametertypen in detail

Behandelt pad-, query-, header- en cookieparameters met serialisatieregels. Studenten vermijden dubbelzinnige parameterdefinities die API-consumenten verwarren.

Les 4 • Beveiliging toepassen op bewerkingen

Laat zien hoe je beveiligingsvereisten globaal en per bewerking kunt toevoegen. Studenten documenteren API's met gemengde beveiliging waarbij sommige endpoints openbaar zijn en andere beveiligd.

Les 1 • Diepgaande verkenning van Swagger Editor

Onderzoekt realtime validatie, automatisch aanvullen en preview-functies van Swagger Editor. Studenten gebruiken de editor efficiënt om specificaties te schrijven en te debuggen.

Les 2 • Branding en aangepaste stijlen

Past aangepaste CSS en logoinjectie toe om Swagger UI af te stemmen op merkrichtlijnen. Studenten leveren een documentatieportaal dat er professioneel uitziet.

Les 3 • API's testen via Swagger UI

Gebruikt de Try It Out-functie om live API-aanroepen uit te voeren vanuit de documentatie. Studenten verifiëren dat hun specificatie het daadwerkelijke API-gedrag nauwkeurig weergeeft.

Les 4 • Swagger UI implementeren

Behandelt npm-, CDN- en Docker-implementatieopties voor Swagger UI. Studenten hosten een werkende documentatiesite vanuit een lokale of cloudomgeving.

Les 1 • Callbacks en webhooks

Behandelt callback-objecten voor het documenteren van asynchrone pushmeldingen en webhooks. Studenten documenteren gebeurtenisgestuurde API's naast traditionele request-response-patronen.

Les 2 • Nieuwe functies in OpenAPI 3.1

Benadrukt volledige JSON Schema-afstemming, webhooks en dialectwijzigingen in schema's in 3.1. Studenten migreren bestaande 3.0-specificaties om te profiteren van nieuwe mogelijkheden.

Les 3 • Specificatie-extensies

Introduceert x- extensievelden voor het toevoegen van leverancierspecifieke metadata aan specificaties. Studenten breiden OpenAPI uit zonder de compatibiliteit met standaard tooling te verbreken.

Les 4 • Omgaan met versiebeheer in specificaties

Behandelt URL-, header- en contenttype-versiestrategieën in OpenAPI-documenten. Studenten documenteren meerdere API-versies zonder volledige specificatiebestanden te dupliceren.

Les 1 • Inleiding tot codegeneratie

Legt uit hoe generators OpenAPI-specificaties parseren om taalspecifieke code te produceren. Studenten begrijpen de relatie tussen specificatiekwaliteit en gegenereerde codekwaliteit.

Les 2 • Mockservers uit specificaties

Genereert mockservers met Prism en Stoplight om parallelle ontwikkeling mogelijk te maken. Studenten ontgrendelen frontend-teams voordat de backend-implementatie is voltooid.

Les 3 • Client-SDK's genereren

Loopt door het genereren van TypeScript-, Python- en Java-clients met OpenAPI Generator. Studenten produceren functionele clientbibliotheken rechtstreeks vanuit hun specificaties.

Les 4 • Contracttesten met specificaties

Gebruikt tools zoals Dredd en Schemathesis om API's te valideren tegen hun OpenAPI-specificaties. Studenten vangen contractschendingen op voordat ze in productie gaan.

Les 1 • Versiebeheer voor specificaties

Past Git-branching-, tagging- en pull request-workflows toe op OpenAPI-bestanden. Studenten beheren de specificatiegeschiedenis met dezelfde nauwkeurigheid als broncode.

Les 2 • Governance en stijlgidsen

Maakt organisatieregels voor het benoemen, opmaken en structureren van OpenAPI-bestanden. Studenten dwingen consistentie af over meerdere API's en teams met behulp van geautomatiseerd linten.

Les 3 • Documentatiepipelines automatiseren

Bouwt CI/CD-pipelines die documentatie bij elke commit valideren, genereren en publiceren. Studenten elimineren handmatige documentatiestappen die drift en fouten introduceren.

Les 4 • Spec-first versus code-first benaderingen

Vergelijkt het ontwerpen van de specificatie vóór het coderen met het genereren van specificaties uit annotaties. Studenten selecteren de juiste benadering op basis van teamstructuur en projectfase.