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.

Sobre Documentación API — OpenAPI y ejemplos

Documentación API — OpenAPI y ejemplos — Estructura openapi.yaml, códigos de error, versionado, ejemplos de peticiones, changelog — mantener docs de API.. Herramientas IT: TLS, docs API, glosario. Use nuestras herramientas sin registro ni instalación de software. Todos los cálculos se realizan en su navegador — sus datos nunca se envían a un servidor.