Express.js
Explica cómo documentar una API Express.js con OpenAPI, schemas, ejemplos, errores, seguridad y validaciones que reduzcan divergencias entre código y contrato.
OpenAPI convierte el contrato HTTP en una especificación legible por personas y herramientas. Solo aporta valor cuando representa el comportamiento real de la aplicación.
Una especificación OpenAPI describe rutas, parámetros, bodies, responses, autenticación y schemas.
contrato OpenAPI
↓
documentación + validación + clientes + testsNo es únicamente una página Swagger. Es una fuente estructurada que puede utilizarse para detectar drift y coordinar equipos.
Sin contrato formal, los consumidores dependen de:
Esto genera diferencias sobre campos opcionales, errores, auth, paginación y versiones.
openapi: 3.1.0
info:
title: Orders API
version: 1.0.0
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Order found
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'404':
$ref: '#/components/responses/NotFound'Cada combinación método-path define una operación. operationId estable facilita SDKs y referencias.
Distingue path, query, header y cookie. Documenta required, defaults, límites y formatos.
Especifica media types y schemas. Un body JSON y un multipart no son intercambiables.
Documenta todos los resultados relevantes, no solo 200. Incluye status, headers y schema de error.
Describe bearer, cookie, OAuth2 o API key. Esto no implementa seguridad; solo declara el contrato.
Representan formatos públicos. No copies automáticamente modelos de base u ORM.
El contrato se diseña antes de implementar. Favorece revisión entre equipos y clientes, pero necesita disciplina para mantener runtime alineado.
Schemas y rutas generan OpenAPI. Reduce duplicación, pero puede documentar accidentalmente decisiones internas y no sustituye diseño.
Definir schemas de runtime reutilizados por validación y OpenAPI suele ser práctico. Aun así, verifica que transformación y responses coincidan.
OpenAPI 3.1 se alinea mejor con JSON Schema moderno. Herramientas antiguas pueden tener soporte parcial. La versión elegida debe seguir el ecosistema real de generación y validación.
const CreateOrderSchema = z.object({
customerId: z.string().uuid(),
items: z.array(z.object({
productId: z.string().uuid(),
quantity: z.number().int().positive(),
})).min(1),
});Una integración puede convertir este schema a OpenAPI, pero debes añadir información que el runtime no conoce automáticamente: descripción, ejemplos, status, seguridad y semántica de negocio.
Problem:
type: object
required: [code, status, message, requestId]
properties:
code:
type: string
status:
type: integer
message:
type: string
requestId:
type: string
details:
type: array
items:
type: objectEnumera códigos relevantes por operación cuando el cliente debe reaccionar.
Documenta:
Los ejemplos deben ser válidos y realistas. Un ejemplo que contiene campos inexistentes degrada la confianza más que no tenerlo.
Puedes validar ejemplos en CI contra los schemas.
El drift ocurre cuando el runtime y la spec divergen.
Controles:
Herramientas de diff pueden señalar:
No toda alerta es realmente breaking y no todo cambio semántico puede detectarse. Revisión humana sigue siendo necesaria.
Un SDK generado reduce trabajo repetitivo, pero hereda defectos del contrato. Revisa:
No obligues a todos los consumidores a regenerar por cambios internos irrelevantes.
La documentación puede exponerse mediante Swagger UI, Redoc o un portal. Protege specs internas si revelan endpoints sensibles, aunque la seguridad no debe basarse en ocultamiento.
oneOf y discriminators con soporte desigual.Un test de integración puede validar la response real contra el schema. También prueba que cada operationId sea único y que referencias no estén rotas.
Integración con PostgreSQL lleva el contrato HTTP hacia persistencia, pooling e integridad.