Pular para o conteúdo principal

OpenAPI / Swagger

A API Ozzie é completamente descrita em uma especificação OpenAPI 3.1. Você pode usá-la para explorar endpoints interativamente, gerar bibliotecas cliente em qualquer linguagem, ou conectar assistentes de IA que integram com o Ozzie automaticamente.

Swagger UI ao vivo​

O explorador de API interativo está disponível em:

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

No Swagger UI você pode:

  • Navegar por todos os endpoints e seus schemas
  • Testar requisições diretamente no browser (clique em Authorize e insira seu token Bearer)
  • Ver exemplos completos de requisição e resposta
  • Baixar a especificação OpenAPI bruta

Baixar a especificação bruta​

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

Usando a especificação com geradores de código​

Você pode gerar um cliente de API com tipagem segura em qualquer linguagem a partir da especificação OpenAPI.

Gerar um cliente TypeScript​

# Passo 1: Instalar o gerador (requer Java ou Docker)
npm install -g @openapitools/openapi-generator-cli

# Passo 2: Baixar a especificação Ozzie
curl https://api.ozzieapp.com/v1/openapi.yaml -o ozzie-openapi.yaml

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

Gerar um 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 (sem 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 a especificação com assistentes de IA​

Assistentes de código com IA (GitHub Copilot, Cursor, Claude) podem usar a especificação OpenAPI para entender a API Ozzie e gerar código de integração automaticamente. Adicione a especificação ao seu projeto e referencie-a nos seus prompts:

# Baixar para um local padrão no seu projeto
curl https://api.ozzieapp.com/v1/openapi.yaml -o docs/ozzie-openapi.yaml

Então no contexto ou prompt do sistema do seu assistente de IA:

Use a API Ozzie para implementar o onboarding de usuários. A especificação OpenAPI completa está em docs/ozzie-openapi.yaml.
Crie um usuário, envie o intake financeiro e gere o plano em uma única função async.

Funcionalidades da especificação​

A especificação OpenAPI da Ozzie inclui:

  • Schemas completos de requisição e resposta para todos os endpoints
  • Valores de enum para todos os campos string (cadence, goal_type, status, etc.)
  • Schemas de resposta de erro para todos os códigos de erro documentados
  • Valores de exemplo realistas em cada anotação example
  • Campos description em cada propriedade — adequados para análise por IA e geração de código
  • Autenticação documentada como esquema http com formato bearer

Mantendo a especificação atualizada​

Você pode automatizar a atualização da especificação no seu pipeline de CI:

# .github/workflows/refresh-spec.yml (executar semanalmente)
- name: Atualizar especificação OpenAPI da Ozzie
  run: curl -sf https://api.ozzieapp.com/v1/openapi.yaml -o docs/ozzie-openapi.yaml

- name: Regenerar cliente TypeScript
  run: |
    openapi-generator-cli generate \
      -i docs/ozzie-openapi.yaml \
      -g typescript-fetch \
      -o src/ozzie-client