Documentación de la API: OpenAPI, Swagger, Postman

TL; DR

OpenAPI es la fuente de la verdad: contrato → SDK → moca → pruebas → portal.
Swagger UI/Redoc - escaparate legible; Postman - scripts ejecutables.
Cosemos linternas, breaking-checks, ejemplos y esquemas de error, generamos servidores SDK y Mock, publicamos un portal dev con versioning y «Sunset».

1) Objetivos y principios

Contrato uno (OpenAPI). Todo lo demás se genera.
Documentación ejecutable: las consultas de ejemplo son probables en Postman/CLI.
Seguridad predeterminada: esquemas de errores, límites, autenticación.
Versioning y ciclo de vida: 'v1 '/' v2', Deprecation/Sunset, changelog.

2) Estructura OpenAPI (esqueleto mínimo)

yaml openapi: 3. 0. 3 info:
title: Payments API version: 1. 2. 0 description: >
Payment transactions: auth/capture/refund/payout. All responses contain trace_id.
servers:
- url: https://api. example. com/v1 tags:
- name: Payments
- name: Payouts components:
securitySchemes:
oauth2:
type: oauth2 flows:
clientCredentials:
tokenUrl: https://idp. example. com/oauth/token scopes:
payments: read: read payments: write: write payments schemas:
Error:
type: object required: [error, error_description, trace_id]
properties:
error: { type: string }
error_description: { type: string }
trace_id: { type: string, format: uuid }
security:
- oauth2: [payments:read]
paths:
/payments/{id}:
get:
summary: Receive payment tags: [Payments]
parameters:
- in: path name: id required: true schema: { type: string, format: uuid }
responses:
'200':
description: Content succeeded:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
'404': { $ref: '#/components/responses/NotFound' }
components:
responses:
NotFound:
description: Content not found:
application/json:
schema: { $ref: '#/components/schemas/Error' }

• Despliega schemas/responses/parameters/requestBodies en 'components'.
• Describa securitySchemes (OAuth2/JWT/HMAC) y aplique en el nivel 'paths'/' global'.

3) Estándar de errores y metadatos

yaml components:
schemas:
ApiError:
type: object required: [error, error_description, trace_id]
properties:
error: { enum: [invalid_request, not_found, rate_limited, internal] }
error_description: { type: string }
trace_id: { type: string, format: uuid }

Siempre documente 429 (límite de tasa), 401/403, y los encabezados 'X-RateLimit-', 'Retry-After'.

4) Ejemplos: request/response, curl y SDK

Para cada endpoint: un ejemplo mínimo y extendido.
Generar curl y código snippets (JS/Python/Go) desde OpenAPI; no escriba con las manos.
Aplique valores reales: UUID, fecha ISO, sumas en «menores» (centros).

yaml examples:
ok:
value:
id: "pay_123"
amount_minor: 1099 currency: "EUR"
status: "captured"
created_at: "2025-11-03T12:34:56Z"

5) Swagger UI/Redoc - cómo publicar

1. Swagger UI (interactivo, try-it-out),

2. Redoc (páginas largas legibles).

Incluye: tema oscuro, búsqueda, selector de versión ('v1', 'v2'), pancarta Depresion.

Ocultar «Try it out» para el dominio prod, permitir en sandbox.

6) Colecciones Postman: guiones en vivo

Autogenere la colección desde OpenAPI y mantenga las variables de entorno ('{{baseUrl}}', '{accessToken}}').
Agregue los pretests (recepción de token) y las pruebas posteriores (assert status/circuitos).
Desglose por carpetas: Auth, Payments, Payouts, Webhooks.
Exporte los monitores (según lo programado) para rutas críticas.

js pm. test("status is 200", () => pm. response. code === 200);
pm. test("schema valid", () => tv4. validate(pm. response. json(), pm. collectionVariables. get("schema_payment")));

7) Moki y sándbox

Generar un servidor mock desde OpenAPI (por ejemplo/' ejemplo '/' ejemplos ').
Denota las limitaciones de los mocos: idempotencia, retrasos, errores aleatorios (para la UAT).
Documenta las diferencias de sandbox vs prod (límites, datos, retrasos).

8) Autogeneración SDK

Desde OpenAPI, genere SDK oficiales (TypeScript, Python, Go).
Política de lanzamientos SDK = SemVer, mapping a la versión de la API.
En README SDK: autenticación, retraídas, idempotencia, tratamiento de 429/Retry-After.

9) Linting, comprobación de las roturas y CI

Linters: spectral (estilos/anti-patrones), openapi-diff (breaking-checks).

• validador de circuito,
• linter,
• test de contrato contra el servidor de mok,
• ensamblaje Swagger/Redoc/colección,
• publicación en el portal (staging→prod),
• Alerta de Deprecation/Sunset.

10) Versioning, Deprecation, Sunset

Versión en URI ('/v1 ') y en' info. version`.
Banderas de obsolescencia: títulos 'Deprecation: true', 'Sunset: <RFC1123 date>', 'Link: <changelog>'.
En el portal: banner y temporizador hasta que se desconecte; Las colecciones Postman para v1 están congeladas (sólo bagfix).

11) Seguridad y privacidad en el muelle

No publique secretos, URL internas, PAN/PII reales.
Para campos sensibles - enmascaramiento y ejemplos-tapones.
Swagger «Try it out» solo → a sandbox, con rate-limits.
Describa claramente OAuth2/OIDC, HMAC (para webhooks) y mTLS (si es necesario).

12) Contratos Style-hyde

Recursos en plural: '/payments ', '/payouts'.
Identificadores: 'pay _', 'po _', UUIDv4 o ksuid.
Fechas - UTC ISO-8601; dinero - 'amount _ minor + currency'.
Paginación - cursor-basado ('? cursor = & limit ='), ordenaciones estables.
Idempotencia - 'Idempotency-Key' para mutaciones.
Objeto estable 'meta' y 'links' para listas.

13) Sección "Webhooks' en el muelle

Sección separada con sobre del evento, firmas HMAC, ventana de tiempo, retrés, códigos de respuesta.
Ejemplos de cuerpos de eventos y la colección Postman para la validación local de firmas.
Endpoints replay/DLQ y lista de verificación UAT.

14) Dev Portal: roles y publicación

Secciones: Revisión, Inicio, Autenticación, Endpoints, Ejemplos, Webhooks, SDK, Restricciones, Changelog.
Roles: API Steward (estándares), Domain Owner (contenido), Tech Writer (edición), DevRel (portal/comunidad).
Ficha: buscar en los campos de esquemas, copiar samples, «recoger la consulta» → Postman.

15) Hojas de cheques

• OpenAPI es válida; linter sin errores.
• Los ejemplos cubren 200/4xx/429/5xx.
• Seguridad: esquemas de auth descritos, sin secretos.
• Formado por Swagger/Redoc y Postman (prod/sandbox).
• Generados por SDK y publicados.
• Changelog y selector de versión actualizados.

• Los títulos de Deprecation/Sunset están habilitados.
• Banner en el portal, cartas a los socios.
• Las métricas de llamadas de la versión obsoleta caen al nivel objetivo.

16) Anti-patrones

Fuentes de verdad duplicadas (wiki ≠ OpenAPI).
Ejemplos «a la vista» sin correr en Postman.
No hay un formato de error único.
Versión «en el parámetro query» en lugar de URI/dominio.
Swagger con acceso prod y sin límites.
Paginación inconsistente y esquemas de autenticación.

17) Mini-snippets de automatización

bash openapi2postmanv2 -s openapi. yaml -o postman. json -p

yaml steps:
- run: spectral lint openapi. yaml
- run: openapi-diff --fail-on-breaking main. yaml openapi. yaml
- run: redoc-cli bundle openapi. yaml -o site/redoc. html
- run: swagger-cli bundle openapi. yaml -o site/swagger. json
- run: openapi2postmanv2 -s openapi. yaml -o site/postman. json -p
- run: npm run deploy:portal

18) Localización y disponibilidad

Individuales 'info. description_<lang>' o dos conjuntos de portal (EN/RU).
Términos en el glosario (KYC/AML, payout, idempotency).
Contraste, navegación por teclado, tema oscuro.

Resumen

Ensambla el transportador de documentación: un único contrato OpenAPI → linters y breaking-checks → escaparates Swagger/Redoc → colección Postman y un servidor moc → SDK → portal dev con versioning y Sunset. Los ejemplos regulares, el formato de error único y la autenticación estricta convertirán la documentación de «PDF en estante» en una herramienta de integración de trabajo, acelerando los partners y reduciendo el costo de soporte.