Com funciona la documentació automàtica d’APIs amb OpenAPI i Scalar?

Trobar-se amb documentació desactualitzada és una de les frustracions més habituals en el desenvolupament de programari actual. No és que els programadors odiïn la documentació en si, sinó el procés tradicional de documentar. Escriure codi és un acte creatiu i dinàmic, mentre que redactar manuals es percep com una tasca administrativa tediosa. Això, sumat al ritme frenètic de les metodologies àgils, on la prioritat és lliurar codi funcional i corregir errors, fa que la documentació acabi sent l’última prioritat. Sempre desplaçada per lliuraments més immediats.

Les conseqüències són concretes. Els desenvolupadors perden hores recorrent al mètode d’assaig i error per esbrinar com funciona una API. Un exemple: provar paràmetres, canviar formats de petició i desxifrar codis d’error sense context. Una tasca que hauria de prendre dues hores pot acabar necessitant dos dies. Simplement perquè el desenvolupador va estar investigant per què l’API no responia com s’esperava.

OpenAPI: un estàndard per acabar amb el caos

L’origen del problema és sempre el mateix. La documentació viu separada del codi. Un PDF o un Wiki neix desactualitzat en el moment que algú canvia un camp al backend i oblida actualitzar el document. OpenAPI resol això d’arrel. És una especificació estàndard per descriure APIs RESTful que permet escriure el manual d’instruccions d’una API en un fitxer de text. Quines rutes existeixen, quins paràmetres rep i quines respostes retorna. Si canvia l’API, canvia el fitxer i la documentació s’actualitza a l’instant.

Però OpenAPI no només manté la documentació sincronitzada. També permet que les eines de testing llegeixin aquest fitxer i verifiquin automàticament si l’API s’està comportant com diu la documentació. Sense necessitat d’escriure proves manualment per a cada canvi. I més enllà de l’automatització de proves, aquest mateix fitxer pot convertir-se en alguna cosa molt més útil que un document estàtic. Eines com Swagger UI el llegeixen i generen una pàgina web interactiva amb la llista d’endpoints, els mètodes HTTP, els paràmetres i els codis de resposta del servidor. És aquí on el desenvolupador pot consultar i provar l’API en temps real. És un salt qualitatiu respecte al PDF de torn. Tanmateix, Swagger UI té una limitació clara: el seu disseny ha envellit malament. La llista vertical amb efecte acordió es torna aclaparadora en APIs grans. A més, l’experiència d’ús deixa molt a desitjar.

Cicle de vida d’una API segons la OpenAPI Initiative: des dels requisits fins al desplegament i les proves.

Scalar: l’evolució de la documentació interactiva

Scalar neix precisament per resoldre el que Swagger UI no resol: l’experiència del desenvolupador. Ofereix una interfície moderna en tres columnes (navegació a l’esquerra, documentació al centre i un client de proves a la dreta) que fa que navegar per una API gran sigui immediat i clar. A més, incorpora un client REST integrat que funciona pràcticament com un mini Postman dins de la pròpia documentació. Molt més complet que el de Swagger UI.

L’elecció entre l’un i l’altre depèn del context. Swagger UI continua sent vàlid per a entorns més conservadors o amb restriccions tècniques concretes. Si la prioritat és l’experiència del desenvolupador i la imatge del producte, Scalar guanya clarament. En qualsevol cas, comparteixen un límit. Tots dos són la solució adequada per a APIs RESTful. Però no per a GraphQL, WebSockets o arquitectures de streaming en temps real, on cal avaluar alternatives específiques.

Interfície de Scalar: documentació, paràmetres i client REST integrat en una mateixa pantalla.

Del codi a la documentació publicada: on entra la IA i com la fem servir

En el flux tradicional, els desenvolupadors escriuen les funcions de l’API utilitzant decoradors o comentaris estructurats en el seu framework. En compilar, el framework genera automàticament un fitxer openapi.json que Scalar llegeix per renderitzar la documentació en temps real. La documentació deixa de ser una tasca separada i passa a ser una conseqüència natural del desenvolupament. Tanmateix, hi ha un matís important que sovint es passa per alt. Sense una intervenció activa, l’únic que es documenta de forma automàtica és el nom de la variable i el seu tipus. Una documentació tècnicament vàlida, però que no aporta valor real a qui ha d’integrar o mantenir aquesta API.

Aquí és on la IA marca la diferència, i on la forma en què s’utilitza determina el resultat. A Itequia, l’ús de la IA en documentació d’APIs no es limita a accelerar l’escriptura de codi. El que fem és analitzar el codi i la documentació existent per identificar tots els endpoints sense documentar o amb documentació obsoleta. També, actualitzar-los de forma sistemàtica.

Aquest anàlisi inclou no només els tipus de cada camp, sinó també:

• Què fa cada camp funcionalment.
• Per què es realitza un determinat càlcul.
• Quins valors estan hardcodejats i quina és la seva justificació (especialment rellevant en sistemes legacy, on els números màgics són habituals i rarament tenen cap explicació escrita).
• Quins són els permisos associats per rol. D’aquesta manera, la documentació deixa de ser un inventari de tipus per convertir-se en un recurs que realment ajuda a entendre i treballar amb l’API.

A més de la revisió del codi existent, incorporem en el flux de treball un pas específic per mantenir aquesta documentació actualitzada de forma contínua. Quan es detecta qualsevol canvi en un endpoint, ja sigui a través d’un pipeline de CI/CD o de la definició d’un workflow en el propi desenvolupament, la documentació s’actualitza automàticament. Això garanteix que el desfasament entre codi i documentació no torni a aparèixer amb el temps.

Documentació amb identitat: plantilles adaptades a cada client

Una documentació ben generada tècnicament pot continuar sent difícil d’usar si no està pensada per a qui la consultarà. Per això, a Itequia proposem i desenvolupem plantilles personalitzades per a cada client. De manera que tinguin el control sobre quina informació volen exposar en la seva documentació, en quin format i amb quin nivell de detall. Aquestes plantilles són reutilitzables entre projectes i es versionen per poder adaptar-se a les necessitats específiques de cada equip o producte. A la pràctica, és una capacitat que es pot aplicar en gairebé qualsevol projecte i que converteix la documentació en un actiu coherent amb la imatge i els estàndards de cada organització.

Per on començar?

El punt de partida és més senzill del que sembla. La majoria de frameworks moderns com FastAPI, NestJS o Spring Boot, amb les llibreries adequades, poden generar el fitxer openapi.json automàticament a partir de les anotacions o la definició dels endpoints en el codi. Amb aquest fitxer generat, integrar Scalar és qüestió de minuts.

El següent pas és incorporar la validació de l’especificació OpenAPI al pipeline de CI/CD. També, definir en quins moments del desenvolupament la IA intervé per enriquir aquesta documentació. Perquè el nivell d’automatització real depèn directament de quan i com es delega en la IA. Si forma part del desenvolupament o de la revisió de cada canvi, la documentació es manté gairebé de forma autònoma. Si no, el resultat serà correcte però superficial.

A Itequia podem revisar com està gestionant el vostre equip la documentació d’APIs i mostrar-vos com automatitzar-la amb OpenAPI, Scalar i IA. Fem una primera revisió inicial sense cost on analitzem el vostre flux actual i us mostrem què es pot automatitzar i en quant temps. Contacteu-nos i expliqueu-nos el vostre cas.

Francesc Juventeny Corberó – Digital Transformation Analyst a Itequia