Pular para o conteúdo
LabS Atlas
AI For Devs
Entrar

OpenAPI

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

OpenAPI (Swagger) é o formato padronizado de documentação de APIs REST que descreve endpoints, esquemas de dados e segurança de forma legível por humanos e por máquinas.

Por ser estruturada e completa, uma especificação OpenAPI é um dos artefatos mais úteis para Interpretação de Artefatos com IA: ela entrega a um modelo de linguagem, em um único documento, o que a API expõe, que dados aceita e devolve e como se autentica. É também a matéria-prima natural para derivar casos de teste de API, positivos e negativos, sem precisar ler o código.

O exemplo de referência mais usado é o Petstore, uma API de pets disponibilizada publicamente pelo próprio Swagger, tanto como especificação no formato OpenAPI 3.1 quanto como projeto Java com Spring em repositório público.

Estrutura de uma especificação

Uma especificação típica se organiza em blocos que o modelo consegue reconhecer e resumir:

  • Informações gerais: título, versão, descrição, termos de uso, contato e licença, no cabeçalho do documento.
  • Servidores: os endereços para onde as requisições são enviadas.
  • Tags: agrupam os endpoints por domínio; no Petstore são três, pet, store e user.
  • Caminhos: os endpoints de cada grupo, com método HTTP, parâmetros e respostas possíveis, como 200, 400, 404 e 422.
  • Componentes: os esquemas de dados (Pet, User, Category, Tag, Order, ApiResponse, entre outros), os corpos de requisição reutilizáveis e os esquemas de segurança. No Petstore há dois métodos de autenticação: um OAuth2 chamado petstore_auth e uma API key enviada no cabeçalho.

Reconhecer a versão do formato já é um sinal de boa leitura. Na comparação registrada em ChatGPT versus Gemini na Interpretação de Artefatos, só um dos modelos identificou que o documento era OpenAPI 3.1.

Como entregar a especificação a um modelo

A especificação pode ir como texto colado no chat ou como arquivo anexado, e a escolha muda o que cada ferramenta consegue processar: algumas versões gratuitas só aceitam texto e imagem. Colada, ela disputa espaço com o limite de contexto. Especificações geradas automaticamente a partir do código crescem rápido, e uma de quase 3000 linhas não coube no prompt.

Mesmo um projeto pequeno pesa: passar o JSON bruto do Swagger direto ao modelo consumiu entre 1200 e 1400 tokens só na entrada. Isso tem efeito direto no Custo de Tokens de qualquer fluxo que repita a chamada por endpoint.

Filtrar antes de enviar

Extrair por código, com regex e manipulação de string sobre o JSON, apenas o método, a URL base, os parâmetros e os exemplos de cada endpoint reduz bastante o consumo. Essa limpeza não usa IA, justamente para não gastar tokens nela.

Da especificação aos testes de API

Entregar o Swagger inteiro e pedir testes tende a gerar pouco: numa tentativa inicial, o modelo apenas raspou a página e listou os endpoints, sem produzir nenhum teste específico. O resultado melhora quando o texto filtrado de um endpoint vai junto com um pedido explícito, um exemplo de entrada descritivo e um formato de saída bem definido. Esse é o caminho detalhado em Geração de Testes de API a partir do Swagger, que chegou a gerar e executar testes de sucesso e de erro contra uma API real.

Quando a especificação é o único contexto disponível, as recomendações de Planejamento de Testes com IA ficam mais genéricas, sobretudo sobre onde testar; combinada ao código-fonte do projeto, ela permite respostas bem mais específicas.