Resposta rápida
OpenAPI é a especificação padrão de mercado para descrever APIs REST em um arquivo JSON ou YAML: quais endereços existem, que dados cada um recebe e devolve e como autenticar. A partir desse arquivo é possível gerar documentação interativa, testar a API no navegador, validar chamadas e criar bibliotecas de acesso em várias linguagens. Swagger é o nome original do padrão e de ferramentas ligadas a ele.
Para que serve
- Documentação interativa, sempre no mesmo formato para todas as APIs.
- Teste direto no navegador ("try it out"), sem escrever código.
- Geração de SDKs e de stubs de servidor.
- Validação automática de requisições e respostas.
- Base do catálogo em plataformas de API Management.
Como manter a documentação atualizada
A forma mais segura é gerar a especificação a partir do código e verificar no pipeline de CI/CD se ela continua igual ao comportamento real da API, bloqueando a publicação quando há divergência. Assim a documentação não fica para trás a cada mudança.