APIのドキュメント、書くのたいへんですよね。
作っても放置されて更新されず誰も読まなくなったなんてこともあると思います。
今回はswaggerを使って、ドキュメントの生成を楽にしてみました。
swaggerとは
swaggerとはAPIドキュメント生成ツールです。
http://swagger.io/
コード内に特定の記述でコメントを含めておくと、コマンド実行でAPIドキュメントを生成してくれます。
今回の環境
多くので言語でライブラリが用意されていますが、
今回はphpのLaravelフレームワークでの使い方を紹介します。
- php
- composer
- Laravel4 or 5
使い方
インストール
まずcomposerで必要ライブラリをインストールします。
Laravelプロジェクトのルート・ディレクトリで実行。
$ composer require zircote/swagger-php
必要ファイル追加
ドキュメントを生成したいControllerのディレクトリにswagger用のphpファイルを配置します。
この記述はディレクトリ内のControllerクラスすべてに適応されます。
xxxにはバージョンとか、アプリ名とかその場にあったものを記述して大丈夫です。
<?php
/**
* @SWG\Swagger(
* host="http://api.example.com",
* schemes={"http", "https"},
* @SWG\Info(
* version="1.0",
* title="xxx のAPIドキュメント",
* ),
* )
*/
Controllerにコメント追加
APIを出力をしているControllerのfunctionに以下のような感じでコメントを追加します。
/**
* @SWG\Get(
* path="/hoge/{hogeID}",
* description="hogeを取得する",
* produces={"application/json"},
* tags={"hoge"},
* @SWG\Parameter(
* name="hogeID",
* description="hogeのID",
* in="path",
* required=true,
* type="string"
* ),
* @SWG\Response(
* response=200,
* description="Success"
* ),
* @SWG\Response(
* response=404,
* description="Parameter error"
* ),
* @SWG\Response(
* response=403,
* description="Auth error",
* ),
* )
*/
public function hoge($userID)
{
return response()->json(['hoge' => 1]);
}
使ったパラメータは以下のような感じです。
- SWG\Get - APIにアクセスするためのメソッド。GetとかPostとか
- path - APIにアクセスするためのパス
- description - APIの説明
- produces - APIが返すcontent-type
- tags - APIのタグ。APIをグルーピングできます。
- SWG\Parameter
- name - パラメータの名前
- description - パラメータの説明
- in - どこのパラメータか (path|query)
- type - パラメータの型
- SWG\Response
- response - ステータスコード
- description - 上のステータスコード時の説明
上記は基本的な項目のみですが、他にも多くのアノテーションが用意されています。
もっと見たい場合は以下で確認できます。
http://zircote.com/swagger-php/annotations.html
コマンド実行
ターミナルよりコマンドを実行するとswagger.jsonファイルが出力されます。
vendor/bin/swagger {swagger-xxx.phpを記述したディレクトリ} -o {swagger.json出力先ディレクトリ}
ブラウザでドキュメント確認
生成したswagger.jsonはswagger-uiに通して見ることによって、ブラウザでAPIドキュメントとして見ることができます。
リンクからdistフォルダをダウンロードし、含まれているindex.html内にてswagger.jsonを読み込んでいる箇所（40行目付近）を探します。
そこに先ほど生成したswagger.jsonのパスを指定してあげれば大丈夫です。
Laravelの場合はpublic以下にディレクトリを作って、
上記のファイルを置いておくとすぐに確認できて便利です。
あとはブラウザで表示するだけ！
成功すると以下のような画面が見れるはずです。
"Try it out!"で実際にAPIにアクセスして、Responseを表示させることもできます。
自分でドキュメントを書いている場合は、返ってくるjsonの項目もツラツラとドキュメントに書き起こしたりすると思いますが、swaggerの場合は実際にAPIが返す値をすぐに確認できるので、とても便利。
実際にAPIが返している値なので、ドキュメントの修正漏れとかが起きる心配も不要ですね。