O que é uma especificação OpenAPI?

OpenAPI Specification, anteriormente conhecido como Swagger, descreve vários aspetos de uma API. Uma especificação OpenAPI (spec) descreve os pontos de extremidade, parâmetros e respostas da API. As especificações OpenAPI são escritas em YAML ou JSON e são usadas por ferramentas para gerar documentação, casos de teste e bibliotecas de clientes. Ao ter uma especificação OpenAPI, os construtores de API podem garantir que sua API seja descrita com precisão, mais acessível e mais fácil de integrar em uma ampla gama 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 por humanos.
• Gere um SDK de cliente. Use ferramentas como 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 está implementada.
• Melhore a colaboração. Forneça a diferentes equipes (front-end, back-end, QA) uma compreensão clara dos recursos e limitações da API, o que ajuda os novos membros da equipe a se envolverem rapidamente.
• Simplifique os testes 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 Centro de API do Azure e o Gerenciamento de API do Azure.
• Simplifique a configuração do gateway de API. Use as especificações da OpenAPI para configurar gateways de API e automatizar tarefas como roteamento, transformações e configurações de compartilhamento de recursos entre origens.

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

Ainda não tens uma especificação OpenAPI?

Escrever uma especificação à mão para uma API que já existe demora tempo, e diverge do que a API realmente faz. Outra opção é registar o que a API devolve e gerar a especificação a partir disso.

Approach	O que obtém	O que observar
Escreve à mão	Controlo total sobre descrições e exemplos	Demora tempo e afasta-se da API real
Gere-o a partir de anotações de código	Uma especificação que se mantém sincronizada com o teu código	Precisas de acesso ao código da API, e o framework tem de o suportar
Gere-o a partir do tráfego registado	Uma especificação para qualquer API que possas invocar, incluindo aquelas que não possuis	Cobre apenas os pedidos que gravaste, por isso exerce as partes da API de que precisas

Dev Proxy regista os pedidos e respostas entre a sua aplicação e uma API, e gera uma especificação OpenAPI a partir deles. Para ver os passos, consulte Gerar uma especificação OpenAPI.

Próximo passo

Gerar uma especificação OpenAPI