Documentación de API con Swagger/OpenAPI

Toda API tiene una documentación. La cuestión es solo dónde vive y desde hace cuánto tiempo es incorrecta. Un archivo Word en una carpeta compartida, una página de wiki, una colección de Postman exportada por un desarrollador que ya se fue, un hilo de conversación donde alguien acabó escribiendo el ejemplo que funciona: son las cuatro formas que adopta de manera espontánea, y todas tienen el mismo defecto. Se escriben al margen del código, así que divergen de él desde el primer commit posterior.

El coste de esta divergencia lo pagan los demás. Un desarrollador de aplicaciones móviles que envía un campo renombrado la semana pasada obtiene un 400 que no entiende, escribe un mensaje, espera una respuesta y pierde media jornada. Multiplíquelo por el número de clientes y por el ritmo de las evoluciones.

OpenAPI aporta una respuesta estructural en lugar de disciplinaria: la descripción de la API se produce a partir del propio código. Las rutas vienen de los @RequestMapping, los esquemas de los DTO y las restricciones de las anotaciones de validación. Renombrar un campo cambia la documentación en el mismo commit, sin que nadie tenga que pensar en ello. Lo que queda por escribir a mano son las intenciones —qué hace un endpoint, por qué puede fallar, qué debe enviar el cliente—, es decir, precisamente lo que el código no puede deducir.