¿Por Qué Probar la Documentación de API?
La documentación es un contrato con los consumidores. Cuando dice que GET /users retorna un JSON con name y email, los consumidores construyen sus integraciones basándose en esa promesa. Si la API retorna username en vez de name, toda integración se rompe.
Tipos de Tests de Documentación
1. Validez de la Especificación
Verifica que el spec OpenAPI/Swagger es válido:
npx @redocly/cli lint openapi.yaml
2. Completitud de la Documentación
Verifica que cada endpoint esté documentado con descripciones, parámetros, respuestas, ejemplos y requisitos de autenticación.
3. Precisión (Detección de Drift)
El test más valioso: verificar que los docs coinciden con el comportamiento real de la API.
Usando Dredd:
npm install -g dredd
dredd openapi.yaml http://localhost:3000
Usando Schemathesis:
pip install schemathesis
schemathesis run http://localhost:3000/openapi.json --checks all
4. Validación de Ejemplos
Verifica que los ejemplos documentados realmente funcionen enviándolos a la API.
Bugs Comunes de Documentación
| Tipo | Ejemplo | Impacto |
|---|---|---|
| Status code incorrecto | Docs dicen 200, API retorna 201 | Consumidores verifican código incorrecto |
| Campo faltante | Docs muestran name, API retorna username | Consumidores obtienen undefined |
| Tipo incorrecto | Docs dicen string, API retorna number | Errores de tipo |
| Error no documentado | 422 no documentado | Consumidores no manejan errores de validación |
Automatización en CI
name: API Doc Testing
on: [push, pull_request]
jobs:
doc-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validar spec
run: npx @redocly/cli lint openapi.yaml
- name: Ejecutar Dredd
run: npx dredd openapi.yaml http://localhost:3000
Ejercicio: Auditoría de Documentación de API
Tarea 1: Validación de Spec
Valida el spec OpenAPI, documenta warnings y errores, corrige y revalida.
Tarea 2: Auditoría de Completitud
Revisa cada endpoint y verifica: descripción, parámetros documentados, respuestas documentadas, ejemplos, auth especificado.
Tarea 3: Detección de Drift
Ejecuta Dredd o Schemathesis. Registra discrepancias. Categoriza cada una.
Tarea 4: Documentación de Errores
Dispara cada condición de error documentada. Compara respuesta real vs documentada.
Tarea 5: Suite de Tests Automatizada
Crea una suite que valide syntax del spec, envíe ejemplos, dispare errores documentados y se ejecute en CI.
Entregables
- Reporte de validación de spec.
- Tabla de auditoría de completitud.
- Reporte de detección de drift.
- Tabla de comparación de documentación de errores.
- Código de suite de tests automatizada.