最近Node.js(Express)で小さいWebAPIの開発をしているのですが、その過程でOpenAPIを導入してみました。
SPAからリクエストする想定もあっての導入だったのですが、その際にいい感じにOpenAPIを扱う方法ってどうやるんだろうと思ったので、少し漁ってみました。
やりたかったこと
- OpenAPIをExpressサーバーで扱う
- あんまりサーバーサイドで頑張らなくていいようにしたい
- どちらかというとWebフロントエンドの開発がメインだったので
- FastAPIみたいにある程度自動で出してくれると嬉しい
OpenAPIをExpressサーバーで扱う
いくつか出てきましたが試したもののみ。
- express-openapi - npm
多分一番出てくる。OpenAPI用な感じでExpressアプリケーションを実装していく。肌に合わない感じがしたのですぐやめました。
便利系
- express-openapi-validator
OpenAPIの定義をもとに、リクエストやレスポンスに対してバリデーションを実装できる
ExpressでREST APIを実装する時にreq/resのvalidationを楽に実装できるライブラリを使ってみた - swagger-ui-express - npm
ExpressアプリケーションにSwagger UIを描画するエンドポイントを追加できるようになる。別途用意したり生成したOpenAPIの定義ファイルを読めるようにしておくと開発したり書きながら確認できるようにもできる。開発環境だけエンドポイントが作られるようにしておけば便利。
後述する express-jsdoc-swagger と合わせて使う方法もあって、この組み合わせはちょっと便利でした。
メモ：ReDocというツールもあって、こっちの方がオシャレなUIだったり便利らしい。
Expressアプリケーションから生成する
OpenAPIで先にAPIを設計し、アプリケーションを組んでいくのがより良い気もします。
ですが、1人開発なのもあって調べ始めた頃は、サーバーアプリケーションの実装をして生成したOpenAPI定義ファイルをWebフロントエンド開発に使えると流れがいいよねと思ってました。
自動生成
どちらも自動生成を狙うタイプのパッケージ。上は開発が止まっていそうで下を使ってみたのですが、上手く動かなかったです。
ちゃんと動けばFastAPIみたいな感じで開発できるのかもしれない…。
JSDocから生成
実装内でJSDocとして component や paths 辺りの記述をしておくとその辺りをかき集めてOpenAPI定義ファイルを生成してくれます。序盤はこれを使ってみていました。
実装の近くに定義を書く事ができるため、追加や削除がしやすいんじゃないかなと思っていました。
実際のところ、実装を変更した場合にJSDoc側の変更が漏れる可能性と付き合っていかないといけないのがストレスでした。
もしかしたらREADMEに書かれている BRIKEV/express-oas-validator: Express OpenAPI Specification (OAS) middleware validator このパッケージ辺りで解消できるのかもしれませんが、そこまでは試せてないです。
結局…
OpenAPIの定義は先に書いてしまったほうがよさそう。
自動生成周りは上手くいかなかったり実装との整合性が取れるのか心配でした。
実装しながら色々考えるより、定義上で整理してしまってexpress-openapi-validator でリクエストもレスポンス(少なくとも開発中は)もバリデーションを有効にして開発する方がトータルの時間は短い気がしました。
バリデーション部分の有効具合は試しきれてないですが、今の所いい感じにガイドしてくれるので体験としてはいいなと思っています。
やってみて
OpenAPIはWebフロントエンド側で型生成して使うくらいしかやったことがなかったので、色々調べつつ作っていく事ができたのはいい経験でした。
色んなサービスが生成できるようにしつつありますが、裏側をなんとなくでも知ると面白いですね