A interface HTTP descrita num documento
A OpenAPI é uma especificação para descrever interfaces de programação de aplicações (APIs) que usam HTTP. Seu formato estruturado informa como chamar as operações do serviço e quais respostas estão previstas, independentemente da linguagem usada no servidor.
Uma ferramenta pode ler esse documento para apresentar documentação navegável ou gerar um cliente que faça as chamadas. A utilidade do resultado depende do conteúdo preenchido e do suporte da ferramenta à versão declarada no campo openapi.
Descrever uma consulta por identificador
Num exemplo didático, a requisição GET /assinaturas/{id} consulta uma assinatura. A descrição declara id como parâmetro do caminho, marca sua presença com required: true e define o tipo integer. O campo responses pode descrever o status 200 para a assinatura encontrada e o 404 para uma assinatura inexistente.
O parâmetro ocupa uma parte do endereço. Para consultar a assinatura 42, você substituiria o marcador por esse número e usaria /assinaturas/42 no endereço do serviço. Os códigos descritos informam as respostas esperadas, mas o exemplo não implementa a consulta nem fornece credenciais para executá-la.
Conferir a descrição contra o serviço
Um documento estruturalmente válido pode descrever uma versão antiga da aplicação. A declaração de um parâmetro obrigatório também precisa corresponder à validação executada pelo servidor.
Você pode comparar uma consulta autorizada a uma assinatura existente com outra a um identificador inexistente. Confira os códigos HTTP e o formato do conteúdo retornado contra o documento da versão testada. Uma divergência exige investigar a implementação e a descrição, pois validar apenas o arquivo não testa a resposta do serviço.
Dúvidas frequentes
Perguntas frequentes sobre OpenAPI
- O documento OpenAPI cria um servidor?
- O documento descreve a interface. Uma ferramenta pode gerar parte do código a partir dele, mas o serviço precisa implementar as operações e executar as verificações de acesso e de entrada.
- O documento precisa usar a linguagem do servidor?
- Não. A especificação é independente da linguagem de programação. A descrição usa JSON ou YAML e deve seguir a versão da OpenAPI declarada no documento.
- Uma descrição válida confirma o comportamento da API?
- Não. A validade da estrutura do documento não confirma que a implementação publicada corresponde a ele. Compare as requisições e as respostas do serviço com a descrição da mesma versão.
Para continuar
Recursos relacionados
Documentação
OpenAPI: especificação oficial
Especificação OpenAPI 3.2.1, com os campos para descrever caminhos, parâmetros e respostas HTTP.
Abrir recursoAplicação na formação
n8n Experts
A integração pode consultar a descrição das operações para conferir entradas e respostas esperadas.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.