OpenAPI (Swagger)

Què és OpenAPI?

OpenAPI és una manera estàndard i llegible per màquines de descriure una API REST. Un sol fitxer, escrit en YAML o JSON, enumera cada endpoint, els paràmetres que reben, la forma de cada petició i resposta, l'autenticació que requereixen i els errors que poden retornar. Swagger era el nom original. Quan l'especificació es va donar a la Linux Foundation va passar a dir-se OpenAPI, i el nom Swagger es refereix ara a les eines construïdes al seu voltant.

La idea és una única font de veritat que tant humans com màquines puguin llegir. A partir d'un sol document OpenAPI pots generar documentació interactiva, SDKs de client en una dotzena de llenguatges, stubs de servidor, servidors mock i proves de contracte. Dos equips poden acordar primer l'especificació i després construir el frontend i el backend en paral·lel contra ella. Una integració de pagaments, per exemple, es pot connectar i provar contra un mock generat molt abans que el servei real estigui llest.

Hi ha dues maneres de treballar. Design-first vol dir que escrius l'especificació a mà i el codi la segueix. Code-first vol dir que anotes el teu codi i l'especificació es genera a partir d'ell. El design-first manté el contracte honest, perquè l'API s'acorda abans que ningú es comprometi amb una implementació. Sigui com sigui, l'especificació deixa de ser documentació que queda obsoleta i es converteix en allò contra el qual es contrasta el sistema.

OpenAPI a Dallonses

Treballem API-first, i OpenAPI és com fem concreta aquesta promesa. A la majoria de projectes l'especificació existeix abans que els endpoints. Acordem el contracte amb el client i els seus altres proveïdors, generem el mock i la documentació, i deixem que els equips de frontend i backend avancin en paral·lel sense bloquejar-se. Quan arriba la implementació real, les proves de contracte la contrasten contra la mateixa especificació, així l'API que es publica coincideix amb la que tothom va signar.

Per a la feina d'integració d'API, un document OpenAPI clar marca la diferència entre un traspàs net i setmanes d'endevinalles. Lliurem als clients una especificació que els seus propis enginyers poden llegir, connectar a les seves eines i en la qual poden confiar. Això és el que compra un enfocament de desenvolupament API-first: sistemes que es connecten amb netedat perquè el contracte es va posar per escrit i es va respectar, no es va descriure en un fil qualsevol.

Construeixes una API en què altres equips han de confiar i connectar-s'hi? Especifiquem-la bé.

Parlem de disseny d'APIs