Testing de Documentación de API

¿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 #

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 #

1. Reporte de validación de spec.
2. Tabla de auditoría de completitud.
3. Reporte de detección de drift.
4. Tabla de comparación de documentación de errores.
5. Código de suite de tests automatizada.