OpenAPI : stop au boilerplate, générez vos clients API

Un “client API” ici c’est un module/classe/objet de fonctions qui vient wrapper les appels API. Par exemple en JS au lieu d’écrire fetch("http://petstore.swagger.io/v1/pets", { method: "POST", body: JSON.stringify({ name: "fido", tag: "dog" }), headers: { ... } }), gérer le parsing, l’authentification, les erreurs etc, on aura juste à faire api.v1.createPets({ name: "fido", tag: "dog" }).

J’étais vraiment sceptique quand j’avais vu ça au début d’OpenAPI (quand ça venait juste de sortir de Swagger) parce que je trouvais ça très prescriptif, que je perdais la main sur mon code. De nos jours je n’ai pas envie de coder un énième api.ts et j’ai appris à lever la main sur ce genre de trucs : il y a des parties de “mon code” que j’accepte être dérivé d’autre chose (ici la spec OpenAPI, en général elle-même générée à partir du code serveur). En plus, les intégrations avec des outils comme Tanstack Query, Typescript etc rendent ça beaucoup plus rentable et utile : tout est validé, typé de bout en bout, tout est connecté aux bons hooks ou mécanisme (timeout, annulation, …).

À voir aussi : ts-rest : un wrapper pour typer ses APIs HTTP

D’autres outils obtiennent ce format « RPC » (« Remote Procedure Call ») sans l’intermédiaire d’un schéma OpenAPI : par exemple tRPC, Hono RPC, ou même les Server Functions dans Next.js marchent très bien dans le contexte d’un monorepo où le backend et le frontend sont côte-à-côte.