Generar clientes y stubs de servidor a partir de un documento OpenAPI y mantenerlos generados

Objetivo

Derivar bibliotecas cliente tipadas y tipos de solicitud y respuesta del lado del servidor a partir del documento OpenAPI, de modo que el documento siga siendo el único contrato y el código escrito a mano no pueda desviarse de él sin que nadie lo note.

Requisitos previos

Un documento OpenAPI que valide, con un operationId en cada operación: la especificación lo define como una cadena única que sirve para identificar la operación, que las herramientas pueden usar con ese fin y de la que los generadores derivan los nombres de los métodos. Un generador cuyo lenguaje de salida pueda leer; OpenAPI Generator enumera generadores de clientes y de servidores por lenguaje. Una decisión sobre dónde vive el código generado: confirmado (commit) en el repositorio o producido durante la compilación.

Pasos

1. Fije la versión del generador en el repositorio (una etiqueta de imagen de contenedor o un script envoltorio). La salida generada cambia entre versiones del generador, y un generador sin versión fija produce diferencias espurias.
2. Genere en un directorio dedicado que no contenga nada escrito a mano. Ponga el comando exacto en el gestor de tareas para que todos, incluida la CI, regeneren de la misma manera.
3. Configure en lugar de editar: la documentación de uso enumera --additional-properties para las opciones del generador, --type-mappings para las sustituciones de tipos y --template-dir para plantillas copiadas cuando la salida necesita cambios estructurales. La documentación de personalización describe .openapi-generator-ignore, basado en .gitignore, como la forma de evitar que el generador sobrescriba los archivos indicados, como un README o un envoltorio que usted mantiene a mano.
4. En los servidores, genere solo interfaces y modelos, impleméntelos en archivos aparte y deje que el compilador señale cada operación que falte o cuya firma haya cambiado.
5. En los clientes, envuelva el cliente generado en una capa fina escrita a mano que añada reintentos, autenticación y registro (logging), de modo que la parte generada pueda reemplazarse por completo.
6. Añada un trabajo de CI que regenere y falle con git diff --exit-code cuando la salida está confirmada; cuando no lo está, haga que la compilación dependa del paso de generación.
7. En cada cambio del documento, regenere, ejecute las pruebas y lea la diferencia del código generado durante la revisión de código: muestra exactamente qué consumidores resultan afectados.

Resultado esperado

Primero cambia el documento OpenAPI y el código lo sigue de forma mecánica; un cambio de contrato que rompería a un consumidor aparece como un error de compilación o como una diferencia en el código generado, y no en tiempo de ejecución.

Límites y base de verificación

Los generadores cubren el subconjunto común de la especificación; los esquemas oneOf complejos, los callbacks y los esquemas de seguridad poco habituales pueden producir código torpe o incorrecto, y la lista de issues del propio generador pasa a formar parte de la dependencia. El código generado es extenso; ese volumen es el precio del contrato. El procedimiento es una síntesis de la documentación citada, no una comparación medida.