Siguiente paso para FastAPI × OpenAPI: proteger automáticamente “APIs que funcionan exactamente como especifica” con generación de SDKs de cliente y pruebas de contrato
Resumen (conclusión primero)
- Después de pulir tu OpenAPI (Swagger UI), el movimiento más efectivo es evolucionarlo de algo que “lees” a algo que “usas” y “haces cumplir”.
- La generación de SDKs de cliente acelera la implementación y mejora la calidad para frontends y otros servicios. Reduce el drift entre tipos y endpoints, y hace que los cambios del spec sean más fáciles de seguir.
- Las pruebas de contrato detectan automáticamente discrepancias entre lo que escribiste en OpenAPI y lo que tu API realmente hace, atrapando cambios rompientes temprano.
- Este artículo, asumiendo el OpenAPI de FastAPI como fuente de verdad, resume opciones de generación de SDK, patrones operativos y ejemplos prácticos centrados en pruebas estilo Schemathesis.
A quién le conviene leer esto
- Desarrolladores en solitario: construyes la API y el frontend tú mismo y luchas constantemente con el drift del spec. Quieres que “los tipos son verdad” sea el default mediante generación de SDKs.
- Equipos pequeños: backend y frontend están separados y revisar specs en PRs es doloroso. Quieres que las pruebas de contrato detecten “breaking changes” temprano.
- Equipos SaaS: tienes integraciones externas y múltiples clientes, y los incidentes de compatibilidad dan miedo. Quieres un proceso de desarrollo centrado en OpenAPI.
Notas de accesibilidad
- Puntos clave al inicio, pasos y checklists a mitad, y resumen al final para mantener un flujo fácil de seguir.
- Términos técnicos se explican brevemente la primera vez y se reutilizan de forma consistente para reducir confusión.
- El código se divide en bloques pequeños y se mantiene al mínimo.
- Nivel objetivo aproximadamente equivalente a AA.
1. La mentalidad: convertir OpenAPI en un “activo”
Ordenar Swagger UI ya tiene valor, pero ir un paso más allá permite que OpenAPI cumpla dos roles más fuertes:
- Convertirse en la “fuente de verdad de tipos” del lado del cliente
Ejemplo: auto-generar SDKs TypeScript o Python para reducir retrabajo en implementación del cliente. - Convertirse en un “contrato exigible” para la implementación
Ejemplo: auto-construir tests desde OpenAPI para detectar desvíos en formas de respuesta o códigos de estado.
Cuando ciclas estas dos cosas, los cambios de API dan mucho menos miedo. El drift entre spec e implementación es más barato de arreglar cuanto antes lo detectas.
2. Panorama de la generación de SDK: qué generas y cómo lo distribuyes
La generación de SDK trata menos de “generar” y más de distribución y flujo de actualización.
2.1 Objetivos típicos de generación
- TypeScript (frontend, Node)
- Python (batch jobs, otros servicios)
- Kotlin/Swift (móvil)
- Go/Java (servicios internos)
2.2 Opciones de distribución
- Commitear el output generado en un repositorio Git (ideal para equipos pequeños, fácil de entender)
- Publicar como paquetes (npm / PyPI / GitHub Packages, etc.)
- Generar dentro de un monorepo y consumir desde el mismo repositorio (mínimo drift)
Si no estás seguro, empezar con “generar en un directorio dedicado de SDK y commitearlo” ya es muy efectivo. Cuando te sientas cómodo, pasar a distribución por paquetes es un siguiente paso natural.
3. Prerrequisitos de OpenAPI que conviene ajustar del lado de FastAPI
Para que la generación de SDK y las pruebas de contrato funcionen bien, ayuda que tu OpenAPI cumpla estas condiciones.
3.1 Las formas de respuesta están fijadas
- Especifica siempre
response_model - Estandariza respuestas de listas (p. ej.,
items + meta) - Unifica errores en un formato compartido (como se cubrió en el artículo anterior)
3.2 Parámetros con descripciones y restricciones
Query(..., ge=0, le=100, description=...)- Haz explícitos los valores enum con
Literal, etc.
3.3 Los códigos de estado coinciden con tu intención
- Crear: 201, Borrar: 204, etc.
- Documenta errores esperados como 404/422/403 mediante
responses
Cuanto mejor se cumplan estas condiciones, mayor será la calidad del SDK—y menos “ruidosas” se vuelven las pruebas de contrato.
4. Generación práctica de SDK: TypeScript como ejemplo
Aquí captamos el flujo conceptual típico: “OpenAPI → cliente TypeScript”.
4.1 El punto de entrada es openapi.json
Con FastAPI, /openapi.json se genera automáticamente. Operativamente, es más estable estandarizar una de estas opciones:
- En CI, hacer
curly guardarlo - Sin levantar la app, llamar
app.openapi()y escribir el JSON
Ejemplo de lo segundo:
# scripts/export_openapi.py
import json
from app.main import app
def main():
spec = app.openapi()
with open("openapi.json", "w", encoding="utf-8") as f:
json.dump(spec, f, ensure_ascii=False, indent=2)
if __name__ == "__main__":
main()
Luego pasas este openapi.json a tu herramienta de generación de SDK.
4.2 Cómo elegir un generador (criterios)
Hay muchas herramientas, pero los ejes de elección son simples:
- ¿El código generado es legible (puedes revisarlo)?
- ¿Los tipos de error y de respuesta son ergonómicos?
- ¿Soporta bien partes de OpenAPI (nullable / oneOf, etc.)?
- ¿Encaja con el ecosistema de lenguaje de tu equipo?
Si quieres empezar pequeño, elige una herramienta enfocada en TypeScript y revisa rápido si te gusta la “sensación” del código generado.
4.3 Ejemplo de uso del SDK generado (conceptual)
Por ejemplo, un API de “listar usuarios” pasa a ser invocable con tipos:
- El tipo de retorno queda fijado
- El rango de
limity campos obligatorios quedan claros - Formas 404 o 422 pueden manejarse como tipos de excepción
Solo esto ya mejora velocidad y confianza en frontend.
5. Pruebas de contrato: verificar automáticamente que la API se comporta como dice OpenAPI
Las pruebas de contrato son, en términos simples: “usar OpenAPI para generar casos de prueba, llamar a la API y detectar desvíos del spec”.
5.1 Por qué es útil
- Detecta mecánicamente el drift entre spec e implementación
- Detiene cambios rompientes en el momento del PR
- Reduce carga de revisión humana
5.2 Qué tipo de drift detecta (ejemplos)
- Un campo documentado en OpenAPI falta en la realidad
- Debería devolver
status_code=201pero devuelve 200 - Strings que exceden
maxLengthpasan - Se devuelven valores fuera de un enum
6. Empezar con pruebas de contrato usando Schemathesis (ejemplo de integración con pytest)
Schemathesis es una herramienta representativa que genera tests desde OpenAPI. Ejemplo mínimo para entender la idea.
6.1 Instalación (ejemplo)
pip install schemathesis pytest
6.2 Ejemplo mínimo de test (referenciando directamente la URL de OpenAPI)
Con la app corriendo (p. ej., http://localhost:8000), lee OpenAPI y prueba.
# tests/test_contract.py
import schemathesis
schema = schemathesis.from_uri("http://localhost:8000/openapi.json")
@schema.parametrize()
def test_api_contract(case):
response = case.call()
case.validate_response(response)
Esto genera múltiples inputs basados en OpenAPI y valida que las respuestas coincidan con el esquema.
6.3 Tips prácticos para reducir ruido
APIs reales tienen auth y dependencias externas, lo que puede hacer que los tests sean inestables. Mitigaciones tempranas efectivas:
- Empezar solo con endpoints públicos (sin auth)
- Reducir alcance por
tag - Posponer endpoints POST/DELETE con alto efecto secundario
- Para valores aleatorios (timestamps, UUIDs), aflojar formatos o usar respuestas fijas
Por ejemplo, reducir por tag podría verse así:
# Ejemplo conceptual (ajusta a las convenciones de tags de tu API)
# schema = schema.include(tags=["public"])
7. Patrones para pruebas de contrato en APIs autenticadas
Si hay autenticación, adjunta un token desde el lado de test. Estos dos patrones son operativamente claros.
7.1 Obtener un token usando un usuario solo de test y reutilizarlo
- Al inicio del test, llamar
/auth/tokenpara obtener token - Adjuntar headers
Authorizationa los casos siguientes
7.2 Simplificar autenticación solo en el entorno de test
- Cuando
ENV=test, permitir un token fijo - O intercambiar dependencias para que “siempre sea el usuario de test”
7.2 suele ser lo más fácil de introducir y entrega valor rápido. Una vez estable, migrar hacia 7.1 es natural.
8. Operacionalizar cambios de spec de forma segura: cómo detectar breaking changes
Con generación de SDK y pruebas de contrato en marcha, lo siguiente que querrás es “detección de diffs”.
8.1 Detectar diffs de OpenAPI en CI
Un flujo típico de automatización en PR para reducir incidentes:
- Exportar
openapi.json - Compararlo con el
openapi.jsonexistente - Fallar si el diff incluye cambios rompientes (eliminar campos, hacer campos requeridos, cambios de tipo, etc.)
Hay muchas herramientas de diff, pero lo más importante es definir de antemano “qué cambios se consideran rompientes”.
8.2 Añadir un paso de deprecación
- No remover de inmediato
- Marcar con
deprecated=True - Dar una ventana de migración
- Si aún hay que remover, pasar a /v2
Con esto, las integraciones externas se vuelven mucho menos aterradoras conforme crecen.
9. Checklist: puntos comunes a mejorar cuando no despega bien
Si la generación de SDK y las pruebas de contrato no fluyen, suele ayudar revisar:
- Muchos endpoints carecen de
response_modelen OpenAPI - Formatos de error no están unificados
- Abuso de
oneOf/anyOfhace la generación incómoda - Pocos ejemplos (
examples), dejando inseguro al usuario del SDK - Auth/dependencias externas vuelven inestables las pruebas de contrato
Empezar con “solo GET públicos” sigue siendo extremadamente valioso. No busques perfección: expandir el alcance gradualmente es lo sostenible.
10. Enlaces de referencia
- FastAPI
- OpenAPI
- Pruebas de contrato
- Generación de SDK (concepto y punto de entrada)
Conclusión
- Tras pulir OpenAPI, pasar a “usar el spec y hacer cumplir el spec” mediante generación de SDK y pruebas de contrato es altamente efectivo.
- La generación de SDK acelera y mejora la calidad del cliente; las pruebas de contrato detectan automáticamente el drift entre spec e implementación.
- Empieza reduciendo alcance. Incluso solo endpoints GET públicos ya dan detección clara de drift y tranquilidad.
- Expande gradualmente el alcance y sigue reflejando diseño de errores, paginación y versionado en OpenAPI—Swagger UI pasa de ser una “doc legible” a una “base de especificación que soporta el desarrollo”.