Genereer OpenAPI uit gedrag met Claude Code, eerlijk

Waarom OpenAPI-contracten uit elkaar lopen (en waarom het ertoe doet)

Een OpenAPI-contract is een gedeelde beschrijving van je API: welke endpoints er zijn, wat je stuurt, wat je terugkrijgt en hoe fouten eruitzien. Het is de afspraak tussen de server en alles wat hem aanroept (een webapp, mobiele app of een andere service).

Het probleem is drift. De draaiende API verandert, maar de spec niet. Of de spec wordt "opgeruimd" om er mooier uit te zien dan de realiteit, terwijl de implementatie vreemde velden blijft teruggeven, statuscodes mist of inconsistente error-shapes heeft. Na verloop van tijd vertrouwen mensen het OpenAPI-bestand niet meer, en wordt het gewoon een document dat iedereen negeert.

Drift ontstaat meestal door normale druk: een snelle fix wordt uitgerold zonder de spec bij te werken, een nieuw optioneel veld wordt "tijdelijk" toegevoegd, paginatie evolueert, of teams updaten verschillende "sources of truth" (backendcode, een Postman-collectie en een OpenAPI-file).

Eerlijk houden betekent dat de spec overeenkomt met het echte gedrag. Als de API soms 409 teruggeeft voor een conflict, hoort dat in het contract. Als een veld nullable is, zeg het. Als auth vereist is, maak het niet vaag.

Een goede workflow levert op:

• Een OpenAPI-file die bedoeld en geobserveerd gedrag weerspiegelt
• Een eenvoudige set checks om drift vroeg te vangen, voordat clients breken
• Concrete client- en server-validatievoorbeelden die je in je codebase kunt kopiëren

Dat laatste punt is belangrijk omdat een contract alleen helpt als het wordt afgedwongen. Een eerlijke spec plus herhaalbare checks verandert "API-documentatie" in iets waarop teams kunnen rekenen.

Begin bij bedoeld gedrag, niet bij code

Als je begint met code lezen of routes kopiëren, zal je OpenAPI beschrijven wat er vandaag bestaat, inclusief eigenaardigheden die je misschien niet wilt beloven. Beschrijf in plaats daarvan wat de API voor een caller zou moeten doen en gebruik de spec om te verifiëren dat de implementatie overeenkomt.

Voordat je YAML of JSON schrijft, verzamel je per endpoint een klein aantal feiten:

• Wat het doet (methode en pad)
• Wat het accepteert (headers, query, path params, body)
• Wat het teruggeeft (succes statuscode, response-vorm, belangrijke headers)
• Wat kan falen (waarschijnlijke fouten, statuscodes, error-body vorm)
• Wie het kan aanroepen (auth en rollen, indien relevant)

Schrijf daarna gedrag als voorbeelden. Voorbeelden dwingen je specifiek te zijn en maken het makkelijker om een consistent contract op te stellen.

Voor een Tasks-API kan een happy-path voorbeeld zijn: “Maak een taak met title en krijg id, title, status en createdAt terug.” Voeg veelvoorkomende fouten toe: “Ontbrekende title geeft 400 met {\"error\":\"title is required\"}” en “Geen auth geeft 401.” Als je al edge cases kent, neem die op: of dubbele titels zijn toegestaan, en wat er gebeurt als een taak-ID niet bestaat.

Vang regels op als simpele zinnen die niet van code-details afhankelijk zijn:

• “title is vereist en 1-120 tekens.”
• “List geeft maximaal 50 items terug tenzij limit is ingesteld (max 200).”
• “dueDate is ISO 8601 date-time.”
• “Write-endpoints vereisen een user token.”

Bepaal tenslotte je v1-scope. Als je het niet zeker weet, houd v1 klein en duidelijk (create, read, list, update status). Bewaar search, bulk-updates en complexe filters voor later zodat het contract geloofwaardig blijft.

Een lichtgewicht template om endpoints te beschrijven

Voordat je Claude Code vraagt een spec te schrijven, noteer gedragsnotities in een klein, herhaalbaar formaat. Het doel is het moeilijk te maken per ongeluk gaten op te vullen met gissingen.

Een goede template is kort genoeg om daadwerkelijk te gebruiken, maar consistent genoeg dat twee mensen hetzelfde endpoint op vergelijkbare wijze zouden beschrijven. Richt je op wat de API doet, niet hoe hij is geïmplementeerd.

Endpoint behavior note template

Gebruik één blok per endpoint:

METHOD + PATH:
Purpose (1 sentence):
Auth:
Request:
- Query:
- Headers:
- Body example (JSON):
Responses:
- 200 OK example (JSON):
- 4xx example (status + JSON):
Edge cases:
Data types (human terms):

Schrijf minstens één concreet request en twee responses. Voeg statuscodes en realistische JSON-bodies met echte veldnamen toe. Als een veld optioneel is, laat in één voorbeeld zien dat het ontbreekt.

Benadruk edge cases expliciet. Dit zijn de plekken waar specs later stilletjes onwaar worden omdat iedereen iets anders dacht: lege resultaten, ongeldige IDs (400 vs 404), duplicaten (409 vs idempotent gedrag), validatiefouten en paginatie-limieten.

Noteer ook datatypes in gewone woorden voordat je aan schema's denkt: strings vs numbers, date-time formats, booleans en enums (lijst toegestane waarden). Dit voorkomt een "mooie" schema die niet overeenkomt met echte payloads.

Stel de OpenAPI-spec op met Claude Code (prompting die werkt)

Claude Code werkt het beste als je het als een zorgvuldige schrijver behandelt. Geef je gedragsnotities en strikte regels voor hoe de OpenAPI eruit moet zien. Als je alleen zegt “schrijf een OpenAPI spec”, krijg je meestal gissingen, inconsistente naamgeving en ontbrekende error-cases.

Plak eerst je gedragsnotities, en voeg dan een strakke instructieblok toe. Een praktisch promptvoorbeeld ziet er zo uit:

You are generating an OpenAPI 3.1 YAML spec.
Source of truth: the behavior notes below. Do not invent endpoints or fields.
If anything is unclear, list it under ASSUMPTIONS and leave TODO markers in the spec.

Requirements:
- Include: info, servers (placeholder), tags, paths, components/schemas, components/securitySchemes.
- For each operation: operationId, tags, summary, description, parameters, requestBody (when needed), responses.
- Model errors consistently with a reusable Error schema and reference it in 4xx/5xx responses.
- Keep naming consistent: PascalCase schema names, lowerCamelCase fields, stable operationId pattern.

Behavior notes:
[PASTE YOUR NOTES HERE]

Output only the OpenAPI YAML, then a short ASSUMPTIONS list.

Als je de draft krijgt, scan dan eerst de ASSUMPTIONS. Dáár wordt eerlijkheid gewonnen of verloren. Keur goed wat juist is, corrigeer wat niet klopt en draai opnieuw met bijgewerkte notities.

Om naamgeving consistent te houden, geef conventies vroeg aan en houd je eraan. Bijvoorbeeld: een stabiel operationId-patroon, tags met alleen zelfstandige naamwoorden, enkelvoudige schema-namen, één gedeeld Error-schema en één auth-scheme-naam die overal wordt gebruikt.

Als je in een vibe-coding workspace zoals Koder.ai werkt, helpt het om de YAML vroeg als een echt bestand op te slaan en in kleine diffs te itereren. Zo zie je welke wijzigingen voortkomen uit goedgekeurde gedragsbeslissingen versus details die het model gokte.

Valideer de spec voordat je hem vergelijkt met de draaiende API

Voordat je iets met productie vergelijkt, zorg dat het OpenAPI-bestand intern consistent is. Dit is de snelste plek om wishful thinking en vage bewoordingen te vinden.

Lees elk endpoint alsof je de client-developer bent. Richt je op wat een caller moet sturen en waarop ze kunnen rekenen om terug te krijgen.

Een praktische review-pass:

• Required vs optional: markeer verplichte velden correct en vermijd "alles optioneel".
• Types en formats: wees expliciet over UUIDs, emails, date-time, min/max waarden.
• Voorbeelden: voeg minstens één realistisch request- en response-voorbeeld per endpoint toe en zorg dat voorbeelden aansluiten op schema's.
• Statuscodes: stem af op je gedragsnotities (create is vaak 201, niet 200). Kies 400 vs 422 en wees consistent.
• Auth: vermeld wat per endpoint vereist is en of rollen toegang beïnvloeden.

Foutresponses verdienen extra aandacht. Kies één gedeelde vorm en hergebruik die overal. Sommige teams houden het heel simpel ({ error: string }), anderen gebruiken een object ({ error: { code, message, details } }). Beide kunnen werken, maar mix ze niet door elkaar. Als je dat doet, groeit clientcode vol speciale gevallen.

Een snelle sanity-scenario helpt. Als POST /tasks title vereist, dan moet het schema dat verplicht markeren, de failure-response laten zien welke error-body je eigenlijk teruggeeft en moet de operatie duidelijk maken of auth vereist is.

Vergelijk de spec met de draaiende API-implementatie

Zodra de spec leest als bedoeld gedrag, behandel de draaiende API als de waarheid voor wat clients vandaag ervaren. Het doel is niet om te "winnen" tussen spec en code. Het doel is verschillen vroeg bloot te leggen en een duidelijke beslissing te nemen over elk verschil.

Voor een eerste ronde zijn echte request/response-samples meestal de eenvoudigste optie. Logs en geautomatiseerde tests werken ook als ze betrouwbaar zijn.

Let op veelvoorkomende mismatches: endpoints die in de ene bron bestaan maar niet in de andere, verschil in veldnaam of -vorm, statuscodeverschillen (200 vs 201, 400 vs 422), ongedocumenteerd gedrag (paginatie, sortering, filtering) en auth-verschillen (spec zegt publiek, code vereist een token).

Voorbeeld: je OpenAPI zegt dat POST /tasks 201 retourneert met {id,title}. Je roept de draaiende API aan en krijgt 200 plus {id,title,createdAt}. Dat is niet "ongeveer hetzelfde" als je client-SDKs van de spec genereert.

Voordat je iets wijzigt, beslis hoe je conflicten oplost:

• Als het gedrag correct maar ongedocumenteerd is: fix de spec.
• Als de spec het afgesproken contract is: fix de code om overeen te komen.
• Als geen van beiden klopt: pas eerst het bedoelde gedrag aan en update dan beide.

Houd elke wijziging klein en reviewbaar: één endpoint, één response, één schema-aanpassing. Dan is het makkelijker te reviewen en opnieuw te testen.

Maak client- en server-validatievoorbeelden vanuit het contract

Als je eenmaal een spec hebt die je vertrouwt, zet die om in kleine validatievoorbeelden. Dit is wat drift uit de deur houdt.

Server-side validatie (weiger slechte requests)

Op de server betekent validatie dat je snel faalt wanneer een request niet aan het contract voldoet, en een duidelijke fout teruggeeft. Dat beschermt je data en maakt bugs makkelijker te vinden.

Een eenvoudige manier om server-validatievoorbeelden uit te drukken is ze als cases te schrijven met drie delen: input, verwachte output en verwachte fout (een foutcode of message-patroon, geen exacte tekst).

Voorbeeld (contract zegt dat title vereist is en 1 tot 120 tekens):

{
  "name": "Create task without title returns 400",
  "request": {"method": "POST", "path": "/tasks", "body": {"title": ""}},
  "expect": {"status": 400, "body": {"error": {"code": "VALIDATION_ERROR"}}}
}

Client-side validatie (vang breaking changes vroeg)

Op de client draait validatie om het detecteren van drift voordat gebruikers het merken. Als de server een andere vorm begint terug te geven, of een verplicht veld verdwijnt, moeten je tests dit signaleren.

Houd clientchecks gericht op waar je echt op vertrouwt, zoals “een taak heeft id, title, status.” Vermijd het afdwingen van elk optioneel veld of exacte volgorde. Je wilt failures bij breaking changes, niet bij onschuldige toevoegingen.

Een paar richtlijnen die tests leesbaar houden:

• Controleer liefst aanwezigheid en type boven exacte waarden.
• Asserteer alleen verplichte velden tenzij een optioneel veld cruciaal is voor je feature.
• Voor fouten, check status en een errorcode, geen volledige berichten.
• Sta extra velden toe tenzij je contract ze expliciet verbiedt.

Als je met Koder.ai werkt, kun je deze voorbeeldcases naast je OpenAPI-file genereren en bijhouden, en ze bijwerken als onderdeel van dezelfde review wanneer gedrag verandert.

Voorbeeldscenario: een eenvoudige Tasks API end-to-end

Stel je een kleine API voor met drie endpoints: POST /tasks maakt een taak, GET /tasks lijst taken en GET /tasks/{id} retourneert één taak.

Begin met het schrijven van een paar concrete voorbeelden voor één endpoint, alsof je het aan een tester uitlegt.

Voor POST /tasks kan het bedoelde gedrag zijn:

• Succes: stuur { "title": "Buy milk" } en krijg 201 met een nieuw taakobject, inclusief een id, de title en done:false.
• Fout 1: stuur {} en krijg 400 met een error zoals { "error": "title is required" }.
• Fout 2: stuur { "title": "x" } (te kort) en krijg 422 met { "error": "title must be at least 3 characters" }.

Wanneer Claude Code de OpenAPI opstelt, moet het snippet voor dit endpoint het schema, statuscodes en realistische voorbeelden bevatten:

paths:
  /tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              ok:
                value: { "title": "Buy milk" }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              examples:
                created:
                  value: { "id": "t_123", "title": "Buy milk", "done": false }
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingTitle:
                  value: { "error": "title is required" }
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                tooShort:
                  value: { "error": "title must be at least 3 characters" }

Een veelvoorkomende mismatch is subtiel: de draaiende API geeft 200 in plaats van 201, of geeft { "taskId": 123 } terug in plaats van { "id": "t_123" }. Dat soort "bijna hetzelfde" breekt gegenereerde clients.

Los het op door één waarheid te kiezen. Als het bedoelde gedrag klopt, pas dan de implementatie aan om 201 en de afgesproken Task-vorm te retourneren. Als productiede gedrag al wordt vertrouwd, update dan de spec (en de behavior notes) om de realiteit weer te geven en voeg de ontbrekende validatie- en errorresponses toe zodat clients niet verrast worden.

Veelgemaakte fouten die een contract oneerlijk maken

Een contract wordt oneerlijk wanneer het stopt met het beschrijven van regels en in plaats daarvan beschrijft wat je API op een goede dag teruggaf. Een simpele test: kan een nieuwe implementatie aan deze spec voldoen zonder de eigenaardigheden van vandaag te kopiëren?

Een valkuil is overfitting. Je legt één response vast en maakt er wet van. Voorbeeld: je API geeft op dit moment dueDate: null voor elke taak, dus de spec zegt dat het veld altijd nullable is. Maar de echte regel kan zijn “vereist wanneer status scheduled is.” Het contract moet de regel uitdrukken, niet alleen de huidige dataset.

Fouten zijn waar eerlijkheid vaak faalt. Het is verleidelijk alleen succesresponses te spec'en omdat die er netjes uitzien. Maar clients hebben de basics nodig: 401 als token ontbreekt, 403 voor forbidden access, 404 voor onbekende IDs en een consistente validatiefout (400 of 422).

Andere patronen die problemen veroorzaken:

• Namen en types wijken af tussen endpoints (taskId in één route en id elders, of priority als string in één response en number in een andere).
• Voorbeelden tegenspreken schema's (enum-waarden komen niet overeen, date-time voorbeelden zijn geen ISO 8601).
• Types worden verbreed om beslissingen te vermijden (alles wordt string, alles optioneel).
• De spec leest als marketingcopy ("snel", "veilig") in plaats van een testbaar contract.

Een goed contract is testbaar. Als je geen falende test uit de spec kunt schrijven, is het nog niet eerlijk genoeg.

Snelle checks voordat je de OpenAPI deelt of publiceert

Voordat je een OpenAPI-file aan een andere team geeft (of in docs plakt), doe een snelle ronde: "kan iemand dit gebruiken zonder in je hoofd te kruipen?"

Begin met voorbeelden. Een spec kan geldig zijn en toch nutteloos als elk request en response abstract is. Voor elke operatie, voeg minstens één realistisch request-voorbeeld en één succesresponse-voorbeeld toe. Voor fouten is één voorbeeld per veelvoorkomend falen (auth, validatie) meestal genoeg.

Controleer daarna consistentie. Als het ene endpoint { "error": "..." } teruggeeft en een ander { "message": "..." }, moet clientcode branching logic bevatten. Kies één error-vorm en hergebruik die, samen met voorspelbare statuscodes.

Een korte checklist:

• Verplichte velden, formats (email, uuid, date-time) en enums zijn expliciet.
• Statuscodes zijn intentioneel en consistent over vergelijkbare endpoints.
• Error-responses bevatten schema én voorbeelden, niet alleen een status.
• Je voert 2-3 echte calls per endpoint uit (tests, curl, Postman of logs) en vergelijkt payloads met de spec.
• Je kunt één kleine clientcall schrijven vanuit de spec zonder headers, veldnamen of nullability te moeten raden.

Een praktisch trucje: kies één endpoint, doe alsof je de API nog nooit gezien hebt, en beantwoord: "Wat stuur ik, wat krijg ik terug, en wat kan breken?" Als de OpenAPI dat niet duidelijk kan beantwoorden, is hij nog niet klaar.

Volgende stappen: maak er een gewoonte van (en houd wijzigingen veilig)

Deze workflow betaalt zich uit als hij regelmatig draait, niet alleen tijdens releases. Kies een eenvoudige regel en houd je eraan: voer hem uit wanneer een endpoint verandert en nogmaals voordat je een bijgewerkte spec publiceert.

Houd eigenaarschap simpel. Degene die een endpoint verandert, werkt de behavior notes en spec-draft bij. Een tweede persoon reviewt de "spec vs implementatie" diff zoals een code review. QA- of support-collega's zijn vaak uitstekende reviewers omdat zij onduidelijke responses en edge cases snel opmerken.

Behandel contractwijzigingen als code-wijzigingen. Als je een chat-gestuurde builder zoals Koder.ai gebruikt, maak dan een snapshot voordat je risicovolle edits doet en gebruik rollback als dat nodig is. Koder.ai ondersteunt ook het exporteren van broncode, wat het makkelijker maakt om spec en implementatie naast elkaar in je repo te houden.

Een routine die meestal werkt zonder teams te vertragen:

• Schrijf behavior notes wanneer je een nieuw endpoint toevoegt
• Valideer de spec en voer contracttests uit vóór het mergen
• Vergelijk de spec met een draaiende API vóór release
• Maak een snapshot vóór risicovolle edits; roll back als diff te verwarrend wordt

Volgende actie: kies één endpoint dat al bestaat. Schrijf 5–10 regels behavior notes (inputs, outputs, error-cases), genereer een draft OpenAPI uit die notities, valideer hem, en vergelijk hem dan met de draaiende implementatie. Repareer één mismatch, retest en herhaal. Na één endpoint blijft de gewoonte vaak plakken.