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.

About API Documentation — OpenAPI & examples

API Documentation — OpenAPI & examples — openapi.yaml structure, error codes, versioning, request examples, changelog — how to maintain API docs.. IT Tools: TLS, API docs, glossary. Use our tools without registration or installing software. All calculations happen in your browser — your data is never sent to a server.