Documentação de API com Swagger/OpenAPI

Toda API tem uma documentação. A única questão é saber onde ela vive e há quanto tempo está errada. Um arquivo Word em um compartilhamento de rede, uma página de wiki, uma coleção do Postman exportada por um desenvolvedor que já saiu da empresa, uma thread de discussão em que alguém acabou escrevendo o exemplo que funciona: essas são as quatro formas que ela assume espontaneamente, e todas têm o mesmo defeito. Elas são escritas ao lado do código e, portanto, divergem dele já no primeiro commit seguinte.

O custo dessa divergência é pago pelos outros. Um desenvolvedor de aplicativo mobile que envia um campo renomeado na semana passada recebe um 400 que não entende, escreve uma mensagem, espera uma resposta e perde meio dia. Multiplique isso pelo número de clientes e pelo ritmo das evoluções.

O OpenAPI traz uma resposta estrutural, e não disciplinar: a descrição da API é produzida a partir do próprio código. Os caminhos vêm dos @RequestMapping, os esquemas vêm dos DTOs, as restrições vêm das anotações de validação. Renomear um campo altera a documentação no mesmo commit, sem que ninguém precise pensar nisso. O que resta para escrever à mão são as intenções — o que um endpoint faz, por que ele pode falhar, o que o cliente deve enviar — ou seja, justamente aquilo que o código não consegue deduzir.