Saltar al contenido principal

OpenAPI / Swagger

La API de Ozzie está completamente descrita en una especificación OpenAPI 3.1. Puedes usarla para explorar endpoints de forma interactiva, generar bibliotecas cliente en cualquier lenguaje, o conectar asistentes de IA que se integren con Ozzie automáticamente.

Swagger UI en vivo​

El explorador de API interactivo está disponible en:

https://api.ozzieapp.com/v1/docs

Desde el Swagger UI puedes:

  • Navegar por todos los endpoints y sus schemas
  • Probar solicitudes directamente en el navegador (haz clic en Authorize e ingresa tu token Bearer)
  • Ver ejemplos completos de solicitud y respuesta
  • Descargar la especificación OpenAPI cruda

Descargar la especificación cruda​

curl https://api.ozzieapp.com/v1/openapi.yaml -o ozzie-openapi.yaml

Usando la especificación con generadores de código​

Puedes generar un cliente de API con tipado seguro en cualquier lenguaje desde la especificación OpenAPI.

Generar un cliente TypeScript​

# Paso 1: Instalar el generador (requiere Java o Docker)
npm install -g @openapitools/openapi-generator-cli

# Paso 2: Descargar la especificación de Ozzie
curl https://api.ozzieapp.com/v1/openapi.yaml -o ozzie-openapi.yaml

# Paso 3: Generar el cliente TypeScript
openapi-generator-cli generate \
  -i ozzie-openapi.yaml \
  -g typescript-fetch \
  -o ./src/ozzie-client \
  --additional-properties=typescriptThreePlus=true,supportsES6=true

Generar un cliente Python​

openapi-generator-cli generate \
  -i ozzie-openapi.yaml \
  -g python \
  -o ./ozzie-python-client \
  --additional-properties=packageName=ozzie_client,projectName=ozzie-client

Usando Docker (sin Java)​

docker run --rm \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/ozzie-openapi.yaml \
  -g typescript-fetch \
  -o /local/src/ozzie-client

Usando la especificación con asistentes de IA​

Los asistentes de código con IA (GitHub Copilot, Cursor, Claude) pueden usar la especificación OpenAPI para entender la API de Ozzie y generar código de integración automáticamente. Agrega la especificación a tu proyecto y referencíala en tus prompts:

# Descargar a una ubicación estándar en tu proyecto
curl https://api.ozzieapp.com/v1/openapi.yaml -o docs/ozzie-openapi.yaml

Luego en el contexto o prompt del sistema de tu asistente de IA:

Usa la API de Ozzie para implementar el onboarding de usuarios. La especificación OpenAPI completa está en docs/ozzie-openapi.yaml.
Crea un usuario, envía el intake financiero y genera el plan en una única función async.

Características de la especificación​

La especificación OpenAPI de Ozzie incluye:

  • Schemas completos de solicitud y respuesta para todos los endpoints
  • Valores de enum para todos los campos string (cadence, goal_type, status, etc.)
  • Schemas de respuesta de error para todos los códigos de error documentados
  • Valores de ejemplo realistas en cada anotación example
  • Campos description en cada propiedad — adecuados para análisis por IA y generación de código
  • Autenticación documentada como esquema http con formato bearer