CicloUrbana tiene ya una API completa: trece endpoints, validación en el borde, DTOs que separan el dominio del contrato y errores uniformes en formato Problem Details. Y sin embargo, todo lo que sabemos sobre ella —qué campos acepta cada endpoint, qué devuelve, qué errores puede dar— vive en el código y en nuestra cabeza. Si mañana el equipo de la app móvil de Ribalta o el del portal de datos abiertos del ayuntamiento quisieran integrarse, tendrían que leer nuestro código o preguntarnos endpoint por endpoint. En esta lección convertimos ese conocimiento tácito en un contrato formal, generado automáticamente desde el propio código, legible por humanos en una interfaz web y por máquinas para generar clientes. Con ella se cierra el módulo 3 y la API de Ribalta queda lista para que otros la usen.

1. Qué es OpenAPI y por qué un contrato legible por máquinas
2. Code-first frente a design-first
3. Integrar springdoc-openapi
4. Metadatos globales: el bean OpenAPI
5. Documentar operaciones: @Tag y @Operation
6. Parámetros y respuestas: @Parameter y @ApiResponse
7. Documentar los DTOs con @Schema
8. Bean Validation en el esquema, automáticamente
9. Documentar los errores Problem Details
10. Agrupar endpoints con GroupedOpenApi
11. Swagger UI: probar la API desde el navegador
12. Exportar el contrato y generar un cliente
13. No exponer Swagger UI en producción
14. Errores Comunes y Consejos
15. Ejercicios

OpenAPI es una especificación para describir APIs HTTP en un documento estructurado, en JSON o YAML. La versión actual es OpenAPI 3.1, que a diferencia de la 3.0 es totalmente compatible con JSON Schema, lo que permite describir estructuras de datos con precisión. Un fragmento del documento de CicloUrbana:

Que sea legible por máquinas es lo que cambia la forma de trabajar:

El contraste con la alternativa —un documento de texto o una página en un wiki— es que esa documentación se desincroniza el primer día: nadie recuerda actualizarla al añadir un campo, y a los tres meses miente. Un contrato generado desde el código no puede mentir.

Hay dos formas de llegar al documento OpenAPI:

El curso usa code-first con springdoc por dos razones: una pedagógica, que se ve la relación directa entre cada anotación y el documento resultante, y otra práctica, que para un equipo pequeño con un solo backend mantener a mano un openapi.yaml de mil líneas cuesta más de lo que aporta.

Ahora bien, conviene entender por qué design-first domina en organizaciones grandes: cuando cinco equipos consumen tu API, el contrato es una negociación previa y no un subproducto. Escribirlo primero permite que el equipo móvil empiece contra un simulador el mismo día que el backend empieza a implementarlo, y evita el riesgo más citado de code-first: que la API acabe siendo un reflejo del modelo interno en lugar de un diseño pensado para quien la consume. Merece la pena notar que en este módulo hemos trabajado, de hecho, design-first sin herramientas: la tabla de los trece endpoints de 03-01 se escribió antes que ningún controlador, solo que vivía en una tabla Markdown y ahora pasa a ser un artefacto formal.

springdoc-openapi inspecciona en ejecución los @RestController, sus anotaciones y sus tipos, y construye el documento OpenAPI. Una sola dependencia:

El sufijo importa: -ui incluye Swagger UI, mientras que springdoc-openapi-starter-webmvc-api genera solo el documento; para una aplicación reactiva sería webflux. Arrancamos y ya hay dos endpoints nuevos, sin escribir una línea:

Los trece endpoints están ahí, con sus parámetros y sus esquemas de respuesta deducidos de los DTOs, y en http://localhost:8080/swagger-ui.html hay una interfaz navegable. Todo el trabajo de las lecciones anteriores —tipos precisos, DTOs específicos, validación declarativa— es lo que hace que esa deducción automática sea buena: un controlador que devolviera Map<String, Object> no produciría nada útil.

La configuración en YAML:

doc-expansion: none merece un comentario: con trece endpoints desplegados la página inicial es una pared de texto, y plegada se ve la estructura de la API de un vistazo.

Las anotaciones documentan endpoints; los metadatos globales —título, versión, contacto, licencia y servidores— se declaran en un bean:

Tres detalles útiles. La lista de Server aparece en Swagger UI como un desplegable, de modo que quien prueba la API elige contra qué entorno lanza las peticiones sin editar URLs. La versión se inyecta con @Value y no se escribe literal, así la documentación siempre dice qué versión está desplegada (en el módulo 7 podrá venir del pom.xml vía Actuator). Y la descripción admite Markdown: es el sitio para las convenciones transversales, como el formato de errores, la paginación o la autenticación.

Las etiquetas agrupan los endpoints en secciones dentro de Swagger UI y se declaran a nivel de clase: @Tag(name = "Estaciones", description = "Consulta y gestión de las estaciones de anclaje de Ribalta") sobre EstacionController.

Y @Operation describe cada método:

El operationId es el atributo que más se descuida y más consecuencias tiene: es el nombre que tendrá el método en los clientes generados. Sin él, springdoc inventa algo como obtenerPorId_1, y ese nombre feo acaba en el código de todos los equipos cliente. Con operationId = "obtenerEstacionPorId", el cliente Kotlin del equipo Android tendrá un obtenerEstacionPorId(id) legible.

@Parameter documenta cada entrada:

Los ejemplos no son decorativos: Swagger UI los precarga en el formulario de "Try it out", así que quien prueba la API por primera vez obtiene una llamada que funciona sin inventarse valores. Y @ApiResponse describe cada respuesta posible:

Con @ExampleObject se documentan cuerpos concretos, algo especialmente valioso cuando el mismo código de estado tiene varias causas:

Swagger UI muestra un desplegable con los dos ejemplos: es la forma más eficaz de explicar los códigos de error del proyecto sin escribir un documento aparte.

Los DTOs de 03-05 se convierten en esquemas OpenAPI, y @Schema los enriquece:

accessMode = READ_ONLY es el más útil y el menos conocido: marca un campo como generado por el servidor, y los generadores de clientes lo excluyen de los objetos de petición, de modo que el cliente no puede intentar enviar bicicletasDisponibles. Es la traducción al contrato de la separación entre DTOs de petición y respuesta.

En los DTOs de petición, requiredMode y los ejemplos son lo importante:

Los enums se documentan solos con su lista de valores, pero merece la pena describir cada estado del dominio de Ribalta:

Aquí llega la recompensa de la lección 03-04. springdoc lee las anotaciones de Bean Validation y las traduce a restricciones del esquema OpenAPI, sin hacer nada.

El esquema generado para CrearEstacionRequest:

Ninguna de esas restricciones se escribió para la documentación: todas venían ya de las anotaciones de validación. Una única fuente de verdad que valida en ejecución y documenta a la vez, sin posibilidad de que se desincronicen.

Las restricciones propias que construimos —@MatriculaBicicleta, @MultiploDe— no las conoce springdoc, así que hay que documentarlas a mano con @Schema(pattern = "^RB-\\d{4}$", example = "RB-0142"). Es un buen argumento a favor de componer las restricciones propias sobre las estándar: si @MatriculaBicicleta se hubiera definido como una anotación compuesta que incluye @Pattern, springdoc habría deducido el pattern solo.

Repetir tres @ApiResponse de error en cada uno de los trece endpoints es exactamente el tipo de repetición que acaba desincronizándose. La solución son anotaciones compuestas propias:

Como ProblemDetail es una clase de Spring, su esquema generado no incluye nuestras extensiones (codigo, traza, errores), así que lo suyo es declarar un esquema propio que las documente:

El campo codigo documentado con "úsalo en tu lógica en lugar del texto" es exactamente la clase de indicación que evita que un cliente compare cadenas y se rompa cuando traduzcamos un mensaje.

Con la API creciendo, un solo documento con todo mezclado se vuelve difícil de navegar. GroupedOpenApi produce varios documentos desde la misma aplicación:

Cada grupo tiene su propio documento en /v3/api-docs/publico, /v3/api-docs/alquileres y /v3/api-docs/interno, y Swagger UI muestra un desplegable para cambiar entre ellos. Los tres usos habituales: separar audiencias, publicando solo el grupo público en el portal del ayuntamiento; separar versiones, con un grupo /api/v1/** y otro /api/v2/**; y generar clientes distintos, uno por grupo, de modo que la app ciudadana no arrastre las operaciones del panel de operarios.

En http://localhost:8080/swagger-ui.html aparece la API completa, agrupada por las etiquetas del apartado 5, y cada operación se despliega mostrando su descripción, sus parámetros con ejemplos, el esquema del cuerpo y todas las respuestas posibles. El botón "Try it out" convierte la documentación en un cliente HTTP: rellena el formulario con los example que declaramos, permite editarlos y ejecuta la petición real contra el servidor elegido en el desplegable, mostrando la respuesta, sus cabeceras, el código de estado y —muy útil para compartir— el comando curl equivalente.

Vale la pena entender qué lo hace útil de verdad, porque no es la herramienta en sí: es que los ejemplos estén bien puestos. Un endpoint documentado sin example obliga a inventarse los valores, y probar POST /api/v1/estaciones sin saber que la capacidad debe ser múltiplo de 6 acaba en un 400. Con los ejemplos, la primera llamada de cualquier desarrollador nuevo funciona. Un detalle para el módulo 5: cuando añadamos JWT, Swagger UI mostrará un botón "Authorize" si declaramos el esquema de seguridad, y a partir de ahí incluirá el token en todas las llamadas.

El documento se puede volcar a un fichero durante el build con el plugin de springdoc, que levanta la aplicación, descarga el JSON y la para:

Requiere el spring-boot-maven-plugin con los objetivos start y stop enlazados a pre-integration-test y post-integration-test. El resultado, target/openapi.json, es el artefacto que se publica: se sube al portal del ayuntamiento, se compara con la versión anterior para detectar cambios incompatibles (módulo 8) y alimenta la generación de clientes con el openapi-generator-maven-plugin:

El generador soporta más de cincuenta lenguajes: java, kotlin, typescript-axios, python, swift5, go. El equipo de la app Android de Ribalta genera su cliente Kotlin desde el mismo openapi.json, y el del portal web su cliente TypeScript.

El código generado tiene esta forma:

Aquí se ve por qué insistimos en el operationId: esos nombres de método salen directamente de él. Y los tipos EstacionDetalleResponse y CrearEstacionRequest se generan a partir de nuestros esquemas, con las mismas restricciones de validación, de modo que el cliente valida antes de enviar porque el contrato las lleva dentro. Un beneficio adicional que se aprecia con el tiempo: si retiramos un campo de un DTO, el cliente generado deja de compilar en la siguiente actualización; un cambio incompatible que en una API sin contrato se descubre en producción, aquí se descubre al compilar.

Swagger UI es una herramienta de desarrollo. En producción es un mapa detallado de tu superficie de ataque: todos los endpoints, todos los parámetros, todos los formatos esperados, y un formulario para probarlos.

La forma más simple de apagarlo es springdoc.api-docs.enabled: false y springdoc.swagger-ui.enabled: false.

Y el enfoque correcto, con perfiles: dejarlo activo en el application.yml base —que usan desarrollo y las pruebas— y desactivarlo en application-prod.yml, que lo sobrescribe al arrancar con --spring.profiles.active=prod. Los perfiles se estudian en 07-02, donde retomaremos esta configuración.

Si el ayuntamiento de Ribalta quiere publicar la documentación de su API abierta, la vía correcta es exportar el openapi.json en el build (apartado 12) y servirlo desde un portal estático independiente, que no expone la aplicación real ni permite lanzar peticiones contra ella. Y un último riesgo: springdoc genera la documentación inspeccionando todos los controladores del contexto, así que un controlador interno olvidado acaba publicado; springdoc.paths-to-match: /api/** es una defensa barata contra ese descuido.

Documentar solo el camino feliz. Un endpoint con solo el 200 documentado obliga al cliente a descubrir los errores en producción. Los @ApiResponse de error son la mitad del valor del contrato.

Olvidar operationId. Los métodos de los clientes generados salen con nombres automáticos y feos, y cambian solos al reordenar el código.

Dejar Swagger UI accesible en producción. Es una descripción completa de tu superficie de ataque.

Poner ejemplos que no funcionan. Un example con capacidad 25 cuando la restricción exige múltiplos de 6 hace que la primera prueba de todo el mundo falle. Copia los ejemplos de peticiones reales.

Documentar la entidad en lugar del DTO. Si @Schema se anota sobre Estacion y el endpoint devuelve EstacionResponse, la documentación describe algo que la API no devuelve.

Repetir los mismos @ApiResponse en cada método. Trece copias que se desincronizan: usa anotaciones compuestas. Y no confíes en que springdoc adivine las restricciones propias: @MatriculaBicicleta no aparece en el esquema, así que añade pattern a mano o compón tu restricción sobre @Pattern.

Consejo: lee el /v3/api-docs como si fueras un cliente externo. Si un campo no se entiende sin abrir el código, falta una description; es la revisión más eficaz y cuesta diez minutos. Y versiona el openapi.json en el repositorio: comparar el generado con el anterior en cada build convierte cualquier cambio incompatible en un fallo de integración continua, antes de que llegue a los clientes.

AlquilerController no tiene ninguna anotación de OpenAPI. Documenta las tres operaciones —iniciar, finalizar y consultar— con sus etiquetas, resúmenes, operationId, parámetros, ejemplos y todas las respuestas de error posibles, incluidas las de negocio de 03-06.

Las operaciones que escriben (POST, PUT, PATCH, DELETE) comparten un conjunto de errores distinto al de las de lectura: además de 400 y 500, pueden dar 409 y 422. Crea @RespuestasErrorEscritura y aplícala, evitando duplicar la definición de los errores comunes.

Configura el build para exportar openapi.json y añade una comprobación que falle cuando un cambio rompa el contrato. Explica qué cambios debe detectar y cuáles debe permitir.

Solución 1.

Dos avisos prácticos. El primero, una colisión de nombres: @RequestBody existe tanto en OpenAPI (io.swagger.v3.oas.annotations.parameters) como en Spring, así que si necesitas la de OpenAPI tendrás que cualificar una de las dos; lo más limpio es poner los ejemplos en el @Schema del DTO, como hace el código anterior. El segundo, y es lo importante del ejercicio: la documentación explica la semántica, no solo los tipos —que finalizar no es idempotente, que el importe no se conoce hasta el final, que la batería mínima depende de la configuración—. Nada de eso se deduce de las firmas Java, y es justo lo que un equipo cliente necesita saber.

Solución 2.

Se aprovecha que las anotaciones compuestas se pueden anidar:

La composición es lo que hace mantenible esta solución: el día que el formato de error cambie —al añadir un campo soporte al esquema, por ejemplo—, se toca RespuestasErrorComunes y el cambio llega a los trece endpoints; si hubiéramos copiado los @ApiResponse, habría trece sitios que actualizar y alguno quedaría atrás. Una advertencia práctica: springdoc lee anotaciones anidadas, pero conviene verificarlo tras crearlas, y la comprobación es directa:

Solución 3.

La exportación es la del apartado 12, enlazando además el arranque y la parada de la aplicación al ciclo de integración con el spring-boot-maven-plugin (start en pre-integration-test, stop en post-integration-test). Después, la comprobación de compatibilidad con openapi-diff frente al contrato publicado:

--fail-on-incompatible devuelve un código de salida distinto de cero si detecta un cambio que rompe a los clientes, lo que hace fallar la integración continua (módulo 8).

Esta tabla es, punto por punto, la de cambios compatibles e incompatibles de la lección 03-01. La diferencia es que allí era una guía que había que recordar y aquí es una comprobación automática que se ejecuta en cada build. Ese es el salto de valor real de tener un contrato formal: convierte una regla de disciplina en una barrera técnica.

El proceso completo al publicar: se genera target/openapi.json, se compara con el publicado y, si el cambio es compatible, se copia sobre openapi-publicado.json y se sube al portal del ayuntamiento. Si es incompatible, la integración continua falla y el equipo decide conscientemente si toca negociar una /api/v2.

El módulo 3 se cierra con la API de CicloUrbana descrita en un contrato formal que se genera solo. Sabes qué es OpenAPI 3.1 y qué desbloquea un contrato legible por máquinas: clientes generados, documentación que no se desincroniza, pruebas de contrato, simuladores y portales de desarrollador. Has comparado code-first y design-first con criterio para elegir según el tamaño del equipo. Integraste springdoc-openapi con una sola dependencia y viste que los trece endpoints aparecían documentados sin escribir nada, porque el trabajo estaba hecho antes: tipos precisos, DTOs específicos y validación declarativa. Configuraste los metadatos globales con el bean OpenAPI, documentaste operaciones con @Tag y @Operation —cuidando el operationId, que acaba siendo el nombre de método en los clientes de otros equipos—, los parámetros con @Parameter y ejemplos que hacen que la primera llamada funcione, y las respuestas con @ApiResponse y @ExampleObject. Enriqueciste los DTOs con @Schema, incluido accessMode = READ_ONLY para los campos que el servidor calcula, y comprobaste que las restricciones de Bean Validation de 03-04 aparecen solas en el esquema: una única fuente de verdad que valida y documenta a la vez. Documentaste los Problem Details de 03-06 con anotaciones compuestas que evitan trece copias, agrupaste con GroupedOpenApi, exportaste el openapi.json en el build y generaste un cliente Java con el openapi-generator-maven-plugin. Y sabes por qué Swagger UI no debe quedar expuesto en producción.

Mira atrás al módulo entero. Empezó con un único endpoint, GET /api/v1/estaciones, que devolvía una lista de objetos de dominio en crudo. Termina con trece endpoints diseñados sobre las restricciones de REST y el nivel 2 de Richardson, con los verbos y códigos de estado correctos, la cabecera Location en las creaciones y ETag para el control de concurrencia. Con validación declarativa en el borde, restricciones propias del dominio de Ribalta e internacionalización en los tres idiomas. Con una jerarquía de DTOs que separa limpiamente lo que CicloUrbana sabe de lo que promete, y un mapeo que permite renombrar en el dominio sin romper a ningún cliente. Con errores uniformes en RFC 7807, un manejador global, códigos estables y trazas correlacionables con el log. Y con un contrato OpenAPI publicable desde el que otros equipos generan su cliente sin preguntarnos nada. La API que verán los ciudadanos de Ribalta está completa.

Le falta, eso sí, lo más elemental: cuando la aplicación se reinicia, todo desaparece. Las cuatro estaciones vuelven a cargarse desde CargadorEstacionesDemo, las bicicletas dadas de alta se esfuman y los alquileres del día se pierden. Todo vive en un ConcurrentHashMap que existe mientras existe el proceso. Hemos podido llegar hasta aquí gracias a haber escondido esa provisionalidad tras la interfaz EstacionRepositorio desde la lección 02-01, una decisión que ahora se cobra su recompensa.

El módulo 4, Acceso a Datos con Spring Boot, la sustituye por persistencia real. Veremos qué son JPA, Hibernate y Spring Data y cómo se relacionan; configuraremos fuentes de datos y un pool de conexiones; convertiremos Estacion, Bicicleta y Alquiler en entidades JPA con sus identificadores y su versión optimista —la que sustituirá al ShallowEtagHeaderFilter de 03-03—; modelaremos las relaciones entre ellas junto con los problemas que ya anticipamos, la carga perezosa y el N+1; usaremos repositorios de Spring Data y sus métodos de consulta derivados; entenderemos las transacciones y por qué @Transactional en el servicio cambia las reglas del juego; y gestionaremos la evolución del esquema con Flyway. Las cuatro estaciones de Ribalta están a punto de sobrevivir a un reinicio.