CicloUrbana ja té una API completa: tretze endpoints, validació a la vora, DTO que separen el domini del contracte i errors uniformes en format Problem Details. I tanmateix, tot el que sabem sobre ella —quins camps accepta cada endpoint, què retorna, quins errors pot donar— viu al codi i al nostre cap. Si demà l'equip de l'app mòbil de Ribalta o el del portal de dades obertes de l'ajuntament es volguessin integrar, haurien de llegir el nostre codi o preguntar-nos endpoint per endpoint. En aquesta lliçó convertim aquest coneixement tàcit en un contracte formal, generat automàticament des del codi mateix, llegible per humans en una interfície web i per màquines per generar clients. Amb ella es tanca el mòdul 3 i l'API de Ribalta queda llesta perquè altres la facin servir.

1. Què és OpenAPI i per què un contracte llegible per màquines
2. Code-first davant de design-first
3. Integrar springdoc-openapi
4. Metadades globals: el bean OpenAPI
5. Documentar operacions: @Tag i @Operation
6. Paràmetres i respostes: @Parameter i @ApiResponse
7. Documentar els DTO amb @Schema
8. Bean Validation a l'esquema, automàticament
9. Documentar els errors Problem Details
10. Agrupar endpoints amb GroupedOpenApi
11. Swagger UI: provar l'API des del navegador
12. Exportar el contracte i generar un client
13. No exposar Swagger UI en producció
14. Errors Comuns i Consells
15. Exercicis

OpenAPI és una especificació per descriure API HTTP en un document estructurat, en JSON o YAML. La versió actual és OpenAPI 3.1, que a diferència de la 3.0 és totalment compatible amb JSON Schema, cosa que permet descriure estructures de dades amb precisió. Un fragment del document de CicloUrbana:

Que sigui llegible per màquines és el que canvia la manera de treballar:

El contrast amb l'alternativa —un document de text o una pàgina en un wiki— és que aquesta documentació es desincronitza el primer dia: ningú no recorda actualitzar-la en afegir un camp, i al cap de tres mesos menteix. Un contracte generat des del codi no pot mentir.

Hi ha dues maneres d'arribar al document OpenAPI:

El curs fa servir code-first amb springdoc per dues raons: una de pedagògica, que es veu la relació directa entre cada anotació i el document resultant, i una altra de pràctica, que per a un equip petit amb un sol backend mantenir a mà un openapi.yaml de mil línies costa més del que aporta.

Ara bé, convé entendre per què design-first domina en organitzacions grans: quan cinc equips consumeixen la teva API, el contracte és una negociació prèvia i no un subproducte. Escriure'l primer permet que l'equip mòbil comenci contra un simulador el mateix dia que el backend comença a implementar-lo, i evita el risc més citat de code-first: que l'API acabi sent un reflex del model intern en lloc d'un disseny pensat per a qui la consumeix. Val la pena notar que en aquest mòdul hem treballat, de fet, design-first sense eines: la taula dels tretze endpoints de 03-01 es va escriure abans que cap controlador, només que vivia en una taula Markdown i ara passa a ser un artefacte formal.

springdoc-openapi inspecciona en execució els @RestController, les seves anotacions i els seus tipus, i construeix el document OpenAPI. Una sola dependència:

El sufix importa: -ui inclou Swagger UI, mentre que springdoc-openapi-starter-webmvc-api genera només el document; per a una aplicació reactiva seria webflux. Arrenquem i ja hi ha dos endpoints nous, sense escriure ni una línia:

Els tretze endpoints hi són, amb els seus paràmetres i els seus esquemes de resposta deduïts dels DTO, i a http://localhost:8080/swagger-ui.html hi ha una interfície navegable. Tota la feina de les lliçons anteriors —tipus precisos, DTO específics, validació declarativa— és el que fa que aquesta deducció automàtica sigui bona: un controlador que retornés Map<String, Object> no produiria res útil.

La configuració en YAML:

doc-expansion: none mereix un comentari: amb tretze endpoints desplegats la pàgina inicial és una paret de text, i plegada es veu l'estructura de l'API d'un cop d'ull.

Les anotacions documenten endpoints; les metadades globals —títol, versió, contacte, llicència i servidors— es declaren en un bean:

Tres detalls útils. La llista de Server apareix a Swagger UI com un desplegable, de manera que qui prova l'API tria contra quin entorn llança les peticions sense editar URL. La versió s'injecta amb @Value i no s'escriu literal, així la documentació sempre diu quina versió està desplegada (al mòdul 7 podrà venir del pom.xml via Actuator). I la descripció admet Markdown: és el lloc per a les convencions transversals, com el format d'errors, la paginació o l'autenticació.

Les etiquetes agrupen els endpoints en seccions dins de Swagger UI i es declaren a nivell de classe: @Tag(name = "Estacions", description = "Consulta i gestió de les estacions d'ancoratge de Ribalta") sobre EstacioController.

I @Operation descriu cada mètode:

L'operationId és l'atribut que més es descuida i més conseqüències té: és el nom que tindrà el mètode als clients generats. Sense ell, springdoc inventa alguna cosa com obtenirPerId_1, i aquest nom lleig acaba al codi de tots els equips client. Amb operationId = "obtenirEstacioPerId", el client Kotlin de l'equip Android tindrà un obtenirEstacioPerId(id) llegible.

@Parameter documenta cada entrada:

Els exemples no són decoratius: Swagger UI els precarrega al formulari de "Try it out", així que qui prova l'API per primera vegada obté una crida que funciona sense inventar-se valors. I @ApiResponse descriu cada resposta possible:

Amb @ExampleObject es documenten cossos concrets, cosa especialment valuosa quan el mateix codi d'estat té diverses causes:

Swagger UI mostra un desplegable amb els dos exemples: és la manera més eficaç d'explicar els codis d'error del projecte sense escriure un document a part.

Els DTO de 03-05 es converteixen en esquemes OpenAPI, i @Schema els enriqueix:

accessMode = READ_ONLY és el més útil i el menys conegut: marca un camp com a generat pel servidor, i els generadors de clients l'exclouen dels objectes de petició, de manera que el client no pot intentar enviar bicicletesDisponibles. És la traducció al contracte de la separació entre DTO de petició i de resposta.

Als DTO de petició, requiredMode i els exemples són l'important:

Els enums es documenten sols amb la seva llista de valors, però val la pena descriure cada estat del domini de Ribalta:

Aquí arriba la recompensa de la lliçó 03-04. springdoc llegeix les anotacions de Bean Validation i les tradueix a restriccions de l'esquema OpenAPI, sense fer res.

L'esquema generat per a CrearEstacioRequest:

Cap d'aquestes restriccions no es va escriure per a la documentació: totes venien ja de les anotacions de validació. Una única font de veritat que valida en execució i documenta alhora, sense possibilitat que es desincronitzin.

Les restriccions pròpies que vam construir —@MatriculaBicicleta, @MultipleDe— springdoc no les coneix, així que cal documentar-les a mà amb @Schema(pattern = "^RB-\\d{4}$", example = "RB-0142"). És un bon argument a favor de compondre les restriccions pròpies sobre les estàndard: si @MatriculaBicicleta s'hagués definit com una anotació composta que inclou @Pattern, springdoc n'hauria deduït el pattern sol.

Repetir tres @ApiResponse d'error a cadascun dels tretze endpoints és exactament el tipus de repetició que acaba desincronitzant-se. La solució són anotacions compostes pròpies:

Com que ProblemDetail és una classe de Spring, el seu esquema generat no inclou les nostres extensions (codi, rastre, errors), així que el més adequat és declarar un esquema propi que les documenti:

El camp codi documentat amb "fes-lo servir a la teva lògica en lloc del text" és exactament la mena d'indicació que evita que un client compari cadenes i es trenqui quan traduïm un missatge.

Amb l'API creixent, un sol document amb tot barrejat es torna difícil de navegar. GroupedOpenApi produeix diversos documents des de la mateixa aplicació:

Cada grup té el seu propi document a /v3/api-docs/public, /v3/api-docs/lloguers i /v3/api-docs/intern, i Swagger UI mostra un desplegable per canviar entre ells. Els tres usos habituals: separar audiències, publicant només el grup públic al portal de l'ajuntament; separar versions, amb un grup /api/v1/** i un altre /api/v2/**; i generar clients diferents, un per grup, de manera que l'app ciutadana no arrossegui les operacions del tauler d'operaris.

A http://localhost:8080/swagger-ui.html apareix l'API completa, agrupada per les etiquetes de l'apartat 5, i cada operació es desplega mostrant la seva descripció, els seus paràmetres amb exemples, l'esquema del cos i totes les respostes possibles. El botó "Try it out" converteix la documentació en un client HTTP: omple el formulari amb els example que vam declarar, permet editar-los i executa la petició real contra el servidor triat al desplegable, mostrant la resposta, les seves capçaleres, el codi d'estat i —molt útil per compartir— l'ordre curl equivalent.

Val la pena entendre què el fa útil de veritat, perquè no és l'eina en si: és que els exemples estiguin ben posats. Un endpoint documentat sense example obliga a inventar-se els valors, i provar POST /api/v1/estacions sense saber que la capacitat ha de ser múltiple de 6 acaba en un 400. Amb els exemples, la primera crida de qualsevol desenvolupador nou funciona. Un detall per al mòdul 5: quan hi afegim JWT, Swagger UI mostrarà un botó "Authorize" si declarem l'esquema de seguretat, i a partir d'aquí inclourà el token a totes les crides.

El document es pot abocar a un fitxer durant el build amb el plugin de springdoc, que aixeca l'aplicació, descarrega el JSON i la para:

Requereix el spring-boot-maven-plugin amb els objectius start i stop enllaçats a pre-integration-test i post-integration-test. El resultat, target/openapi.json, és l'artefacte que es publica: es puja al portal de l'ajuntament, es compara amb la versió anterior per detectar canvis incompatibles (mòdul 8) i alimenta la generació de clients amb l'openapi-generator-maven-plugin:

El generador suporta més de cinquanta llenguatges: java, kotlin, typescript-axios, python, swift5, go. L'equip de l'app Android de Ribalta genera el seu client Kotlin des del mateix openapi.json, i el del portal web el seu client TypeScript.

El codi generat té aquesta forma:

Aquí es veu per què insistim en l'operationId: aquests noms de mètode surten directament d'ell. I els tipus EstacioDetallResponse i CrearEstacioRequest es generen a partir dels nostres esquemes, amb les mateixes restriccions de validació, de manera que el client valida abans d'enviar perquè el contracte les duu a dins. Un benefici addicional que s'aprecia amb el temps: si retirem un camp d'un DTO, el client generat deixa de compilar a l'actualització següent; un canvi incompatible que en una API sense contracte es descobreix en producció, aquí es descobreix en compilar.

Swagger UI és una eina de desenvolupament. En producció és un mapa detallat de la teva superfície d'atac: tots els endpoints, tots els paràmetres, tots els formats esperats, i un formulari per provar-los.

La manera més simple d'apagar-lo és springdoc.api-docs.enabled: false i springdoc.swagger-ui.enabled: false.

I l'enfocament correcte, amb perfils: deixar-lo actiu a l'application.yml base —que fan servir desenvolupament i les proves— i desactivar-lo a application-prod.yml, que el sobreescriu en arrencar amb --spring.profiles.active=prod. Els perfils s'estudien a 07-02, on reprendrem aquesta configuració.

Si l'ajuntament de Ribalta vol publicar la documentació de la seva API oberta, la via correcta és exportar l'openapi.json al build (apartat 12) i servir-lo des d'un portal estàtic independent, que no exposa l'aplicació real ni permet llançar peticions contra ella. I un últim risc: springdoc genera la documentació inspeccionant tots els controladors del context, així que un controlador intern oblidat acaba publicat; springdoc.paths-to-match: /api/** és una defensa barata contra aquest descuit.

Documentar només el camí feliç. Un endpoint amb només el 200 documentat obliga el client a descobrir els errors en producció. Els @ApiResponse d'error són la meitat del valor del contracte.

Oblidar operationId. Els mètodes dels clients generats surten amb noms automàtics i lletjos, i canvien sols en reordenar el codi.

Deixar Swagger UI accessible en producció. És una descripció completa de la teva superfície d'atac.

Posar exemples que no funcionen. Un example amb capacitat 25 quan la restricció exigeix múltiples de 6 fa que la primera prova de tothom falli. Copia els exemples de peticions reals.

Documentar l'entitat en lloc del DTO. Si @Schema s'anota sobre Estacio i l'endpoint retorna EstacioResponse, la documentació descriu alguna cosa que l'API no retorna.

Repetir els mateixos @ApiResponse a cada mètode. Tretze còpies que es desincronitzen: fes servir anotacions compostes. I no confiïs que springdoc endevini les restriccions pròpies: @MatriculaBicicleta no apareix a l'esquema, així que afegeix-hi pattern a mà o compon la teva restricció sobre @Pattern.

Consell: llegeix el /v3/api-docs com si fossis un client extern. Si un camp no s'entén sense obrir el codi, hi falta una description; és la revisió més eficaç i costa deu minuts. I versiona l'openapi.json al repositori: comparar el generat amb l'anterior a cada build converteix qualsevol canvi incompatible en una fallada d'integració contínua, abans que arribi als clients.

LloguerController no té cap anotació d'OpenAPI. Documenta les tres operacions —iniciar, finalitzar i consultar— amb les seves etiquetes, resums, operationId, paràmetres, exemples i totes les respostes d'error possibles, incloses les de negoci de 03-06.

Les operacions que escriuen (POST, PUT, PATCH, DELETE) comparteixen un conjunt d'errors diferent del de les de lectura: a més de 400 i 500, poden donar 409 i 422. Crea @RespostesErrorEscriptura i aplica-la, evitant duplicar la definició dels errors comuns.

Configura el build per exportar openapi.json i afegeix una comprovació que falli quan un canvi trenqui el contracte. Explica quins canvis ha de detectar i quins ha de permetre.

Solució 1.

Dos avisos pràctics. El primer, una col·lisió de noms: @RequestBody existeix tant a OpenAPI (io.swagger.v3.oas.annotations.parameters) com a Spring, així que si necessites la d'OpenAPI n'hauràs de qualificar una de les dues; el més net és posar els exemples al @Schema del DTO, com fa el codi anterior. El segon, i és l'important de l'exercici: la documentació explica la semàntica, no només els tipus —que finalitzar no és idempotent, que l'import no es coneix fins al final, que la bateria mínima depèn de la configuració—. Res d'això no es dedueix de les signatures Java, i és just el que un equip client necessita saber.

Solució 2.

S'aprofita que les anotacions compostes es poden imbricar:

La composició és el que fa mantenible aquesta solució: el dia que el format d'error canviï —en afegir un camp suport a l'esquema, per exemple—, es toca RespostesErrorComunes i el canvi arriba als tretze endpoints; si haguéssim copiat els @ApiResponse, hi hauria tretze llocs per actualitzar i algun quedaria endarrere. Un advertiment pràctic: springdoc llegeix anotacions imbricades, però convé verificar-ho després de crear-les, i la comprovació és directa:

Solució 3.

L'exportació és la de l'apartat 12, enllaçant a més l'arrencada i l'aturada de l'aplicació al cicle d'integració amb el spring-boot-maven-plugin (start a pre-integration-test, stop a post-integration-test). Després, la comprovació de compatibilitat amb openapi-diff davant del contracte publicat:

--fail-on-incompatible retorna un codi de sortida diferent de zero si detecta un canvi que trenca els clients, cosa que fa fallar la integració contínua (mòdul 8).

Aquesta taula és, punt per punt, la de canvis compatibles i incompatibles de la lliçó 03-01. La diferència és que allà era una guia que calia recordar i aquí és una comprovació automàtica que s'executa a cada build. Aquest és el salt de valor real de tenir un contracte formal: converteix una regla de disciplina en una barrera tècnica.

El procés complet en publicar: es genera target/openapi.json, es compara amb el publicat i, si el canvi és compatible, es copia sobre openapi-publicat.json i es puja al portal de l'ajuntament. Si és incompatible, la integració contínua falla i l'equip decideix conscientment si toca negociar una /api/v2.

El mòdul 3 es tanca amb l'API de CicloUrbana descrita en un contracte formal que es genera sol. Saps què és OpenAPI 3.1 i què desbloqueja un contracte llegible per màquines: clients generats, documentació que no es desincronitza, proves de contracte, simuladors i portals de desenvolupador. Has comparat code-first i design-first amb criteri per triar segons la mida de l'equip. Vas integrar springdoc-openapi amb una sola dependència i vas veure que els tretze endpoints apareixien documentats sense escriure res, perquè la feina estava feta abans: tipus precisos, DTO específics i validació declarativa. Vas configurar les metadades globals amb el bean OpenAPI, vas documentar operacions amb @Tag i @Operation —tenint cura de l'operationId, que acaba sent el nom de mètode als clients d'altres equips—, els paràmetres amb @Parameter i exemples que fan que la primera crida funcioni, i les respostes amb @ApiResponse i @ExampleObject. Vas enriquir els DTO amb @Schema, inclòs accessMode = READ_ONLY per als camps que el servidor calcula, i vas comprovar que les restriccions de Bean Validation de 03-04 apareixen soles a l'esquema: una única font de veritat que valida i documenta alhora. Vas documentar els Problem Details de 03-06 amb anotacions compostes que eviten tretze còpies, vas agrupar amb GroupedOpenApi, vas exportar l'openapi.json al build i vas generar un client Java amb l'openapi-generator-maven-plugin. I saps per què Swagger UI no ha de quedar exposat en producció.

Mira enrere al mòdul sencer. Va començar amb un únic endpoint, GET /api/v1/estacions, que retornava una llista d'objectes de domini en cru. Acaba amb tretze endpoints dissenyats sobre les restriccions de REST i el nivell 2 de Richardson, amb els verbs i codis d'estat correctes, la capçalera Location a les creacions i ETag per al control de concurrència. Amb validació declarativa a la vora, restriccions pròpies del domini de Ribalta i internacionalització en els tres idiomes. Amb una jerarquia de DTO que separa netament el que CicloUrbana sap del que promet, i un mapatge que permet reanomenar al domini sense trencar cap client. Amb errors uniformes en RFC 7807, un gestor global, codis estables i rastres correlacionables amb el log. I amb un contracte OpenAPI publicable des del qual altres equips generen el seu client sense preguntar-nos res. L'API que veuran els ciutadans de Ribalta està completa.

Li falta, això sí, el més elemental: quan l'aplicació es reinicia, tot desapareix. Les quatre estacions es tornen a carregar des de CarregadorEstacionsDemo, les bicicletes donades d'alta s'esfumen i els lloguers del dia es perden. Tot viu en un ConcurrentHashMap que existeix mentre existeix el procés. Hem pogut arribar fins aquí gràcies a haver amagat aquesta provisionalitat darrere de la interfície EstacioRepositori des de la lliçó 02-01, una decisió que ara es cobra la seva recompensa.

El mòdul 4, Accés a Dades amb Spring Boot, la substitueix per persistència real. Veurem què són JPA, Hibernate i Spring Data i com es relacionen; configurarem fonts de dades i un pool de connexions; convertirem Estacio, Bicicleta i Lloguer en entitats JPA amb els seus identificadors i la seva versió optimista —la que substituirà el ShallowEtagHeaderFilter de 03-03—; modelarem les relacions entre elles juntament amb els problemes que ja hem anticipat, la càrrega mandrosa i l'N+1; farem servir repositoris de Spring Data i els seus mètodes de consulta derivats; entendrem les transaccions i per què @Transactional al servei canvia les regles del joc; i gestionarem l'evolució de l'esquema amb Flyway. Les quatre estacions de Ribalta estan a punt de sobreviure a un reinici.