API documentation

OpenAPI spec

The REST API description standard: openapi.yaml — paths, methods, request/response schemas, error codes. Generates: docs (Swagger UI, Redoc), clients, mocks, tests.

Minimal structure

info (name, version) → servers → paths (/users/{id}: get/post) → components/schemas (DTOs) → security (bearerAuth). Write the spec before code — API-first.

Errors

Document all codes: 400 validation (with fields), 401/403, 404, 409 conflict, 429 rate-limit, 500. One error format across the API: {code, message, details}.

Versioning

/v1/ in the path — simplest and explicit. A header — for minor changes. Deprecation: Sunset header + 6 months migration. Breaking change = new version, never otherwise.

Examples

Every endpoint — with real request/response examples (not foo/bar). A working copy-paste cURL. A Postman collection next to the spec.

Changelog

An API changelog — a separate doc: new endpoints, schema changes, deprecations with removal dates. Publish with releases, subscription for API consumers.

Over API-documentatie — OpenAPI & voorbeelden

API-documentatie — OpenAPI & voorbeelden — openapi.yaml-structuur, foutcodes, versiebeheer, request-voorbeelden, changelog — API-docs onderhouden.. IT-tools: TLS, API-docs, glossarium. Gebruik onze tools zonder registratie of software-installatie. Alle berekeningen gebeuren in uw browser — uw gegevens worden nooit naar een server gestuurd.