Open APIのドキュメント作成ツール、Stoplight Studio使ってみました。
これ、すごいですね！
今までは、Swagger Editorでyamlをゴリゴリ書いていたのですが、今後もうそんなことをすることはなさそうです。
Open APIのドキュメントとは
Open APIドキュメントは、REST APIの仕様書のことです。APIのドキュメント仕様が乱立していたのは今は昔、今はこのOpen APIがスタンダードです。
AMLまたはJSONで書くことができ、バージョン管理に入れるのが普通です。またhtmlにビルドして、社内サーバやCloudFrontなどで、関係者がシームレスに見られるように配置することができます。
REST APIの仕様をこの形式で書いていない現場、例えばExcelやパワポで管理しているような現場は見限った方がいいと言えるぐらい、浸透しています。
Open APIはSwaggerというツールで書きます。昔は仕様のこともSwaggerと言っていましたが、いつしかOpen APIというワードが登場し、仕様をOpen API、ツール群のことをSwaggerと呼ぶ様になりました。
Open APIのYAMLは長くなりがちで、通常のYAMLのフォーマットやリンターで書いていくのは辛いです。かといってVSCodeやJetbrainsにもめぼしいプラグインなどはありません。私はこれまで、Swagger Editorというもので書いていました。Swagger Editorは、ブラウザ上で使用できるOpen APIの記述に特化したエディタです。ローカルで起動することもできますが、環境設定が大変です。
Stoplight Studioを導入
きっかけ
最近、スクラッチでREST APIを構築する案件にジョインしました。バックエンドは私一人で、Open APIのドキュメントも用意されていなく、APIのパラメータは作りながら考えていくという状況でした。
つまり実装と同時並行で、Open APIのドキュメントも作っていかないといけない状態です。
APIの数が多いので、ドキュメント用意するのが大変です。何かいいツールないかと思って調べていたら、Stoplight Studioにたどりつきました。
導入作業
Stoplight StudioはSwagger Editor同様、Web上でもローカルでも、どちらでも使えるようです。
インストールが簡単みたいだったので、ローカルにインストールして使いました。私は公式からパッケージをダウンロードしてしまったのですが、Homebrewでもいけるみたいですね。
brew install --cask stoplight-studio
使ってみた感想
少しクセがあって最初は手間取りましたが、ちょっと使っていたら、だんだん慣れてきて使えるようになりました。
公式でもサンプルが用意されているので、参考にしてみるのもいいかもしれません。
使っていて個人的にクセがあるな思ったポイントは
- 左のペインの右クリックを使うより、なるべくメニューの+アイコンから操作した方が良さそう
- Formの画面から構成要素を新規作成していくより、まずは構成要素を作成しておいて、Formから参照設定した方が良さそう
といったところでしょうか。
ところどころ、操作が直感的でなく難しいです。あと、タグの設定がEnter押下やマウスクリックで消えたりしまう。バグっぽいので、これはそのうち修正されると思いますが。
それ以外は、使っていて快適でした。特に、JSONからModel定義をgenerateできるのとかがいいです。このツールのおかげで、Open APIのドキュメントがサクサク作れるようになりました。もうSwagger Editorで自分でYAMLを記述する環境には戻れないです。
まとめ
Stoplight Studioを使ってみた感想でした。
Stoplightはチームで共有したりモックサーバをサクッと立てたりする便利な機能が有料で提供されているみたいですが、個人でOpen APIドキュメント生成目的で使うのでも全然いいと思います。
このツールのおかげで、あまり好きでなかったOpen APIドキュメント生成のタスクが好きになりそうです。
