Express+OpenAPIで開発を始める際にいくつか試してみたこと
最近Node.js(Express)で小さいWebAPIの開発をしているのですが、その過程でOpenAPIを導入してみました。
SPAからリクエストする想定もあっての導入だったのですが、その際にいい感じにOpenAPIを扱う方法ってどうやるんだろうと思ったので、少し漁ってみました。
やりたかったこと
- OpenAPIをExpressサーバーで扱う
- あんまりサーバーサイドで頑張らなくていいようにしたい
- どちらかというとWebフロントエンドの開発がメインだったので
- FastAPIみたいにある程度自動で出してくれると嬉しい
OpenAPIをExpressサーバーで扱う
いくつか出てきましたが試したもののみ。
express-openapi An unopinionated OpenAPI framework for express. Latest version: 12.1.3, last published: 2 years ago. Start using express-openapi in your project by running `npm i express-openapi`. There are 48 other projects in the npm registry using express-openapi. npm
多分一番出てくる。OpenAPI用な感じでExpressアプリケーションを実装していく。肌に合わない感じがしたのですぐやめました。
便利系
GitHub - cdimascio/express-openapi-validator: 🦋 Auto-validates api requests, responses, and securities using ExpressJS and an OpenAPI 3.1.x or 3.0.x specification 🦋 Auto-validates api requests, responses, and securities using ExpressJS and an OpenAPI 3.1.x or 3.0.x specification - cdimascio/express-openapi-validator GitHub
OpenAPIの定義をもとに、リクエストやレスポンスに対してバリデーションを実装できる
https://note.com/shift_tech/n/n66f43685f2f9
ExpressアプリケーションにSwagger UIを描画するエンドポイントを追加できるようになる。別途用意したり生成したOpenAPIの定義ファイルを読めるようにしておくと開発したり書きながら確認できるようにもできる。開発環境だけエンドポイントが作られるようにしておけば便利。
後述する express-jsdoc-swagger と合わせて使う方法もあって、この組み合わせはちょっと便利でした。
メモ：ReDocというツールもあって、こっちの方がオシャレなUIだったり便利らしい。
Expressアプリケーションから生成する
OpenAPIで先にAPIを設計し、アプリケーションを組んでいくのがより良い気もします。
ですが、1人開発なのもあって調べ始めた頃は、サーバーアプリケーションの実装をして生成したOpenAPI定義ファイルをWebフロントエンド開発に使えると流れがいいよねと思ってました。
自動生成
express-swagger-generator Generates swagger doc & ui based on express existing routes.. Latest version: 1.1.17, last published: 5 years ago. Start using express-swagger-generator in your project by running `npm i express-swagger-generator`. There are 26 other projects in the npm registry using express-swagger-generator. npm swagger-autogen This module performs automatic construction of Swagger documentation. It can identify the endpoints and automatically capture methods such as get, post, put, and so on. It also identifies paths, routes, middlewares, response status codes, parameters in th. Latest version: 2.23.7, last published: 2 years ago. Start using swagger-autogen in your project by running `npm i swagger-autogen`. There are 38 other projects in the npm registry using swagger-autogen. npm
どちらも自動生成を狙うタイプのパッケージ。上は開発が止まっていそうで下を使ってみたのですが、上手く動かなかったです。
ちゃんと動けばFastAPIみたいな感じで開発できるのかもしれない…。
JSDocから生成
実装内でJSDocとして component や paths 辺りの記述をしておくとその辺りをかき集めてOpenAPI定義ファイルを生成してくれます。序盤はこれを使ってみていました。
実装の近くに定義を書く事ができるため、追加や削除がしやすいんじゃないかなと思っていました。
実際のところ、実装を変更した場合にJSDoc側の変更が漏れる可能性と付き合っていかないといけないのがストレスでした。
もしかしたらREADMEに書かれている BRIKEV/express-oas-validator: Express OpenAPI Specification (OAS) middleware validator このパッケージ辺りで解消できるのかもしれませんが、そこまでは試せてないです。
結局…
OpenAPIの定義は先に書いてしまったほうがよさそう。
自動生成周りは上手くいかなかったり実装との整合性が取れるのか心配でした。
実装しながら色々考えるより、定義上で整理してしまってexpress-openapi-validator でリクエストもレスポンス(少なくとも開発中は)もバリデーションを有効にして開発する方がトータルの時間は短い気がしました。
バリデーション部分の有効具合は試しきれてないですが、今の所いい感じにガイドしてくれるので体験としてはいいなと思っています。
やってみて
OpenAPIはWebフロントエンド側で型生成して使うくらいしかやったことがなかったので、色々調べつつ作っていく事ができたのはいい経験でした。
色んなサービスが生成できるようにしつつありますが、裏側をなんとなくでも知ると面白いですね