こんにちは、鈴木商店の若林 (itigoore01) です。
皆さんはAPI仕様書をどうやって記述されていますか？
鈴木商店はもともと↓のようなスプレッドシートにAPI仕様書を記述していました。
このスプレッドシートでAPI仕様書を記述することが大変だったことは、みなさんも想像に容易いかと思います……。
しかしフォーマットは違うにせよ、似たような苦しみを感じている方もいらっしゃるのではないでしょうか？
今回はそんなAPI定義書の作成に苦労している子羊に手を差し伸べてくれる救世主、Stoplight Studio のご紹介です。
鈴木商店でのAPI仕様書の使い方
まず鈴木商店ではAPI仕様書をどのように活用しているか、何のために書いているか、から説明します。
鈴木商店ではAPI仕様書を主に「フロントエンドエンジニアとバックエンドエンジニアとの認識共有」を行うために使用しています。
鈴木商店では、フロントエンドの実装がAPIの実装より先行することが多く、またフロントエンドの実装者とバックエンドの実装者は別の人であることがほとんどです。
そのため、API定義書を作成し、リクエスト、レスポンスの形式を決めておくことで、バックエンドとフロントエンドの実装を並列で進められるようにする、という狙いがあります。
他の用途としては「バックエンドの実装前にインターフェイスだけレビューを受けられる状態にするため」、「新規参画するエンジニアのため（将来のため）」などがあります。
一般公開されるAPIは鈴木商店では作成することがないので、あくまで内部向けのドキュメントという位置づけです。
なお、API定義書の作成者はバックエンドエンジニアに限らず、フロントエンドエンジニアが行うこともあります。
Stoplight Studio にたどり着くまでの試行錯誤の歴史
Stoplight Studio の紹介の前に、鈴木商店が Stoplight Studio にたどり着くまでの試行錯誤の歴史を紹介します。
そんなの良いから Stoplight Studio がどんなものか、早く教えて！という方は Stoplight Studio とは までジャンプしてください。
OpenAPIの定義を手で書いてみた
やっぱり標準化されているもので定義したいよね！という軽い気持ちで、OpenAPIのyamlを手書きで記述して、API定義書の作成を試みたことがあります。
以下がOpenAPIの定義の例です。
例えば↓のようなAPIを定義するのに……
こんなにyamlを書く必要があります。
（縦に長過ぎるので、画像を小さくしています。画像クリックで拡大して見れます。）
どうでしょう、たかだか20個程度のAPIを定義するだけで、700行以上書く必要があるのはなかなかの記述量だとは思いませんか？
これをプロジェクトで最低でも50以上はあるAPIの定義を記述していくのは、頭がおかしくなりそうだったため、OpenAPIを手で記述することは諦めました。
Swagger PHPで定義してみた
鈴木商店では Laravel を主に使用しているので、Swagger PHP を使って、コード側にAPI定義を記述パターンも試してみたことがあります。
GitHub – zircote/swagger-php: A php swagger annotation and parsing library
ただ、これはこれで記述量が多い！！！
なんならOpenAPI の yaml を書くよりもしんどい可能性すらあるな、という感じでした。
Swagger PHP の記述例 (Swagger PHPのExamplesより引用)
また、そもそもAPI定義書は「APIが完成していない間にも、フロントエンドが実装を進められるようにする」という目的で使用しているため、コードファースト的なアプローチではタイミング的に遅く、スキーマファイル的なアプローチでないと成り立たないな、ということでこれも廃案となりました。
マークダウンで定義を書く
鈴木商店では esa というナレッジベースを使用しているのですが、esa がマークダウンで書けるので、API定義書も esa で共有することにしました。
マークダウンなので軽くかけるため、最初はかなりいい感じでした。
人によってバラバラな記述にならないようにテンプレートを用意しつつ、自由度の高さを生かして必要なところはコメントを多めにしたりなど、かなりやりたいことにハマっていました。
ただ、開発の中終盤になって、あらゆるAPIで共通のモデルに変更が入ったことで、マークダウンでのしんどさにぶち当たりました。
「このやり方だと共通のモデル全部修正するのしんどくない……？」
もちろん共通のモデルは別で定義しておいて、各API定義ではリンクだけ貼る、みたいな工夫をしてもいいのですが、それはそれで各API定義を見ただけでは定義が完全に把握できなくなってしまう問題があります。
マークダウンでの記述は割とやりたいことにハマっていたので、これらのデメリットには目を瞑るしかないのか……と、このころは考えていたのでした。
Stoplight Studio とは
Stoplight Studio とは Open API の定義を GUI で行えるツールです。
API Design & Documentation Management | Designing & Building OpenAPIs | Stoplight
鈴木商店ではアプリ版を使用していますが、クラウド版もあるようです。
GUIはこんな感じ。
モデルを参照することができるので、このようなモデルを定義しておき……
定義したモデルをレスポンスボディとして参照する、といったことができます。
それ以外にも様々な機能があるのですが、それらも含めたStoplightを使用するのメリットを紹介します。
メリット
yamlでOpenAPIを書かなくていい
yamlで50本以上のAPI定義を記述するのは頭がおかしくなりそうな苦行ですが、Stoplight Studio を使うとGUIでAPI定義書を作成できます。
個人の感想ですが、 yaml を手で書くより10倍は早く、楽に作成できます。
正直、この点だけでも超オススメできます。
Open APIの作成以外にもいろんな機能がある
GUIでOpenAPIを書けるだけでも十分メリットですが、他にもいろんな機能があります。
- OpenAPIの定義に従ってモックサーバーを立てる
- きれいなUIのAPIドキュメントをHTMLで出力できる
などなど……。
他にも機能があるので、ぜひ公式サイトをご覧ください！
Open API のエコシステムを使える
最終的にStoplightを使ってもOpenAPIのファイルが出来上がるだけなので、Open API向けのさまざまなエコシステムを利用できます。
例えば OpenAPI Generatorを使って、API定義からAPIクライアント、APIのスタブ生成などができたりします。
これなんかは独自形式のAPI定義書だと受けられない恩恵ですよね！
まとめ
これまでの鈴木商店がAPI仕様書の作成で苦労してきた歴史なんかも紹介しながら、Stoplight Studioの良さを紹介してみましたが、いかがでしたでしょうか？
API仕様書の作成で苦しんでいる方は、ぜひStoplight Studioをお試しください！
