現在フリーランスとしてプロジェクトマネジメントやサーバサイド開発をやっているzee8です。今回は、GAOGAO Advent Calendar 2019への投稿として、最近API仕様書作成用に使い始めたOpenAPI/Swaggerについて書いてみたいと思います。

前提

前提として、以下のようなプロジェクトでのお話です。（念のため申し添えておくと、GAOGAOとは関係のないプロジェクトですので、詳細を記すのは控えます。）

現行で動いているモバイルアプリの一部リプレースプロジェクト
RESTではなくJSON-RPCっぽい設計のAPIを作り直す作業
データベースを引き継ぐ必要があるので、APIのリクエスト・レスポンスのデータ構造は極力変えないようにしたい

最初にやったこと

最初は素直にSwagger EditorをDockerを使ってローカルで動かして仕様を書き始めましたが、すぐに以下の理由でつらくなってきました。

プレビューがあるのはいいが、エディタとしての機能が貧弱
最終的にAPIエンドポイントが100以上になる予定なのに、1ファイルに全て収める必要がある

公式ツールが全く実用的でないことに若干驚きながらも、不都合を解消するためのツールを探し始めました。あまり時間をかけて調査したわけではないのでベストの選択だとは思っていませんが、今のところ以下のツールで対応しています。

VSCodeのSwagger Viewer

Swagger Editorのエディタとしての機能が貧弱なのが問題であれば、逆によく使うエディタでプレビューできれば良いと考えて探したところ、VSCodeのSwagger Viewerというextensionが見つかりました。記述を間違えたときのエラーがSwagger Editorよりさらに分かりにくいという欠点はありますが（GitHubのTODOにも"Show all the errors during validation"と書いてあるので問題は認識されている模様）、いったんこれでyamlを頑張って書いています。

Speccy

作成したAPI仕様書の共有は、Amazon S3上に配置したSwagger UIで行っているため、最終的には全てのAPIエンドポイントを1つのファイルに収める必要があるものの、長大な1つのファイルを編集し続けるのはつらすぎます。複数のSwagger/OpenAPIファイルをまとめるツールがいくつか見つかったのですが、なんとなくWeWorkの人が作っているSpeccyというCLIツールを使っています。Speccyでできることは以下のとおりです。

lint
- 指定したファイルのOpenAPIの仕様に合っていないところや不適切なところを指摘。
resolve
- OpenAPIでは、$refという記載でcomponentsに定義したオブジェクトを参照できることになっており、別ファイルを参照している$refを元の定義に置き換えて1つのファイルにまとめる。
serve
- ReDocを使って、ビューワを起動。（私個人はこちらは未使用）

かなりシンプルなツールなのでコマンドの使い方に迷うことはありませんが、resolveの際に以下のような問題があることを把握しています。（私のOpenAPIの仕様の理解が足りないだけの可能性もあり。）

$refで多重に参照している定義がうまく解決されないっぽい
- index的なファイル1つと各カテゴリごとのファイルの2階層に限定して暫定対応。
example: "2019-01-23" example: "2019-01-23 12:34:56"といったようなdateやdatetimeの例のクォーテーションマークが削除されてしまい、Swagger UIで正しく表示されない
- sedコマンドでクオーテーションマークを元に戻すことで暫定対応……
- OpenAPIの仕様的にはdateやdatetimeはstring扱いであるはずなのでやめてほしい。

今のところの所感

今のところ上記の対応をしつつかなり初歩的なレベルで使っているだけですが、OpenAPIを使うことについて以下のように考えています。

そもそもyamlを直接書くのはつらい
- Stoplight Studioなどを使うべきか。
RESTじゃないAPIの仕様は書きにくい
- 逆に考えると、妙に個性的なAPIの設計を避ける効果はありそう。
仕様からのコード生成までいかないとあまりメリットがなさそう
- 既に（社内などに）実績のある仕様書のテンプレートがあるなら、それを使い続けてもいいかも。
- 今回は既存で使えるテンプレートがなかったため、フォーマットが決まっているだけでもメリットはあると感じている。
OpenAPIを使っても仕様書の集約は難しい
- 使い始める前はモバイルアプリの開発者とサーバサイドAPIの開発者が同じ仕様書を見て作業できるのは素晴らしいと思っていたが、当然ながらモバイルアプリの開発者が必要な情報とサーバサイドAPIの開発者が必要な情報は異なるわけで、それらを全部押し込むとかなり分かりにくい仕様書になってしまう。結局は別々の仕様書があったほうが分かりやすいということになる。
意外とツールが整備されていない
- OpenAPI.Toolsを見ても分かるように、ツールが乱立している状態で良いもの・自分に合ったものを探すのに時間がかかる。
- 場合によっては自前で作ったほうが良い場合もあるかも。

ネガティブなことばかり書いてしまいましたが、まだまだ活用できていないからネガティブなところが目についてしまうのだろうというのと同時に、きちんと活用するまでには相当の労力が必要そうという印象を持っています。最近はPostmanで仕様書を作っている人もいるようなので、そちらも試してみたいと思います。