Gerar clientes e stubs de servidor a partir de um documento OpenAPI e mantê-los sempre gerados

Objetivo

Derivar bibliotecas cliente tipadas e tipos de requisição e resposta do lado do servidor a partir do documento OpenAPI, de modo que o documento continue a ser o contrato único e o código escrito à mão não possa divergir dele sem ser notado.

Pré-requisitos

Um documento OpenAPI válido, com um operationId em todas as operações: a especificação define-o como uma string única usada para identificar a operação, que as ferramentas podem usar para identificar operações, e os geradores derivam daí os nomes dos métodos. Um gerador cuja linguagem de saída você consiga ler; o OpenAPI Generator lista geradores de cliente e de servidor por linguagem. Uma decisão sobre onde fica o código gerado: commitado no repositório ou produzido durante o build.

Passos

1. Fixe a versão do gerador no repositório (uma tag de imagem de contêiner ou um script wrapper). A saída gerada muda entre versões do gerador, e um gerador sem versão fixa produz diffs espúrios.
2. Gere para um diretório dedicado que não contenha nada escrito à mão. Coloque o comando exato no task runner, para que todos, incluindo o CI, regenerem da mesma forma.
3. Configure em vez de editar: a documentação de uso lista --additional-properties para opções do gerador, --type-mappings para substituições de tipos e --template-dir para templates copiados quando a saída exige alterações estruturais. A documentação de customização descreve o .openapi-generator-ignore, modelado a partir do .gitignore, como a forma de impedir que o gerador sobrescreva os arquivos listados, como um README ou um wrapper mantido à mão.
4. Para servidores, gere apenas interfaces e modelos, implemente-os em arquivos separados e deixe o compilador apontar cada operação que esteja em falta ou cuja assinatura tenha mudado.
5. Para clientes, envolva o cliente gerado numa camada fina escrita à mão que adicione retentativas, autenticação e logging, de forma que a parte gerada possa ser substituída por completo.
6. Adicione um job de CI que regenere o código e falhe com git diff --exit-code quando a saída é commitada; quando não é, faça o build depender da etapa de geração.
7. A cada alteração do documento, regenere, execute os testes e leia o diff do código gerado durante a revisão: ele mostra exatamente quais consumidores são afetados.

Resultado esperado

O documento OpenAPI muda primeiro e o código acompanha de forma mecânica; uma alteração de contrato que quebraria um consumidor aparece como erro de compilação ou como diff no código gerado, e não em tempo de execução.

Limites e base de verificação

Os geradores cobrem o subconjunto comum da especificação; esquemas oneOf complexos, callbacks e esquemas de segurança incomuns podem produzir código estranho ou incorreto, e a lista de issues do próprio gerador passa a fazer parte da dependência. O código gerado é verboso; o volume é o preço do contrato. O procedimento é uma síntese da documentação citada, não uma comparação medida.