5Fase 5 · SDD Lifecycle
Contrato API y API Manager
Contract-first · OpenAPI antes que código · Gobierno de la exposición
7/14
Flujo contract-first
OpenSpec → OpenAPI → API Manager → Backend implementation
Ejemplo de contrato OpenAPI
paths:
/api/v1/transactions:
get:
summary: Search user transactions
operationId: searchTransactions
security:
- oauth2: []
parameters:
- {name: startDate, in: query, schema: {type: string, format: date}}
- {name: endDate, in: query, schema: {type: string, format: date}}
- {name: minAmount, in: query, schema: {type: number}}
- {name: maxAmount, in: query, schema: {type: number}}
- {name: page, in: query, schema: {type: integer}}
- {name: size, in: query, schema: {type: integer}}
responses:
"200": {description: Paginated list of transactions}
"400": {description: Invalid filters}
"401": {description: Unauthorized}
"403": {description: Forbidden}
Validación del contrato
npm run openapi:validate
spectral lint openapi.yaml
openapi-generator validate -i openapi.yaml
Qué gobierna el API Manager
Seguridad
OAuth2, políticas de acceso, rate limiting, cuotas por cliente
Versionado
Gestión de versiones y deprecación controlada de contratos
Observabilidad
Analytics, trazabilidad, consumo desagregado por cliente
Catálogo
Documentación pública, suscripción y portal de desarrolladores
✓ Gate 5 — API Governance Ready
✓
OpenAPI válido y con ejemplos✓
Naming y versionado correctos✓
Security scheme definido (OAuth2)✓
Errores estándar 400/401/403/500✓
Paginación estándar (page/size)✓
CorrelationId definido✓
API publicada en API Manager✓
Políticas de seguridad aplicadas