O que é uma especificação OpenAPI?

A especificação OpenAPI, anteriormente conhecida como Swagger, descreve vários aspectos de uma API. Uma especificação OpenAPI (especificação) descreve os endpoints, parâmetros e respostas da API. As especificações do OpenAPI são escritas em YAML ou JSON e são usadas por ferramentas para gerar documentação, casos de teste e bibliotecas de cliente. Ao ter uma especificação OpenAPI, os criadores de API podem garantir que sua API seja descrita com precisão, mais acessível e mais fácil de integrar em uma ampla variedade de aplicativos e serviços.

Veja por que você deve considerar ter uma especificação OpenAPI para sua API:

  • Documente uma API de forma padronizada. Documente uma especificação de API em um formato consistente e legível.
  • Gere um SDK de cliente. Use ferramentas como o Kiota para automatizar a geração de bibliotecas de clientes em várias linguagens de programação.
  • Crie uma API simulada. Crie servidores fictícios com base na especificação da API, o que ajuda você durante os estágios iniciais de desenvolvimento, quando a API real ainda não foi implementada.
  • Melhore a colaboração. Forneça a diferentes equipes (front-end, back-end, controle de qualidade) uma compreensão clara dos recursos e limitações da API, o que ajuda os novos membros da equipe a se atualizarem rapidamente.
  • Simplifique o teste e a validação. Automatize a validação de solicitações e respostas de API em relação à especificação, o que facilita a identificação de discrepâncias.
  • Integre com ferramentas de gerenciamento de API. Integre, implante e monitore facilmente suas APIs com muitas ferramentas e gateways de gerenciamento de API, como o Azure API Center e o Gerenciamento de API do Azure.
  • Simplifique a configuração do gateway de API. Use as especificações do OpenAPI para configurar gateways de API e automatizar tarefas como roteamento, transformações e configurações de compartilhamento de recursos entre origens.

Usando as especificações do OpenAPI, você pode criar APIs bem projetadas e documentadas de forma consistente. Eles também são mais fáceis de manter e usar tanto internamente quanto por consumidores externos.

Ainda não tem uma especificação openapi?

Escrever uma especificação à mão para uma API que já existe leva tempo e se afasta do que a API realmente faz. Outra opção é registrar o que a API retorna e gerar a especificação a partir disso.

Approach O que você obtém O que observar
Escreva à mão Controle total sobre descrições e exemplos Leva tempo, e se afasta da API real
Gerar a partir de anotações de código Uma especificação que permanece em sincronia com seu código Você precisa ter acesso ao código da API e o framework tem que dar suporte a ela
Gere-o a partir do tráfego registrado Uma especificação para qualquer API que você possa invocar, incluindo as que você não possui Ele abrange apenas as solicitações que você registrou, portanto, exerça as partes da API de que você precisa

Dev Proxy registra as solicitações e respostas entre seu aplicativo e uma API e gera uma especificação OpenAPI a partir delas. Para obter as etapas, consulte Gerar uma especificação OpenAPI.

Próxima etapa

Gerar uma especificação OpenAPI

  • Última atualização em