（コメント欄まで読んでいただけると。。）
皆さんはAPIのドキュメント書いてますか？最近仕事でLaravel使ってAPIを作ったので、その仕様を他の開発者に共有しなきゃと思ったところで、そういえばドキュメント作ってなかったなーということに気づき、swagger-php&Swagger UIで作り始めました。しかし、Swaggerは下記のような記述をエンドポイントごとに書く必要があり、非常に メンドくさい！しかもエンドポイントを増やす度に書かなくてはならず、レビューの必要が出てくるのでコストになります。
/**
* @OA\Get(
* path="/api/resource.json",
* @OA\Response(response="200", description="An example resource")
* )
*/
もうちょっと簡単にドキュメント生成できないかなーと調べていたところに良さげなのを発見しました。
Laravel API Documentation Generator
mpociot/laravel-apidoc-generator
Automatically generate your API documentation from your existing Laravel routes.
なんと、Laravelアプリのルーティング情報から自動でドキュメントを生成してくれるらしく、下記の2コマンドだけでドキュメント生成ができちゃいます。
1. composer require mpociot/laravel-apidoc-generator
2. php artisan api:generate --routePrefix="api/*"
では、実際に試してみたいと思います。
インストールと準備
下記でvendorに（とりあえず、stableバージョン）追加して、
$ composer require mpociot/laravel-apidoc-generator
んで、Controllerを追加。（すでに作ってある場合は不要）
<?php
namespace App\Http\Controllers;
use App\Http\Requests\APIRequest;
use Illuminate\Http\Request;
class APIController extends Controller
{
/**
* 暇を持て余した
*
*
*
* 神々の
*
*
*
* 遊び
*
*/
public function index(APIRequest $request)
{
//
}
}
あと、リクエストクラスも作成。（すでに作ってある場合は不要）
<?php
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
class APIRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
*
* @return bool
*/
public function authorize()
{
return true;
}
/**
* Get the validation rules that apply to the request.
*
* @return array
*/
public function rules()
{
return [
'hogehoge' => 'required|integer|between:5,10',
'hoge_name' => 'string|min:1',
];
}
}
routes/api.phpに追記するのを忘れずに！
Route::get('index', 'APIController@index');
ドキュメント生成
下記のコマンドを叩きます。
$ php artisan api:generate --routePrefix="api/*"
Processed route: [GET] api/index
Wrote index.md to: public/docs
Generating API HTML code
Wrote HTML documentation to: public/docs/index.html
Generating Postman collection
http://127.0.0.1:8000/docs/index.html へアクセスすると...
なんかできてるーーーー！！
肝心のドキュメントは...。
おお〜Docコメントが表示されてますね。
Requestクラスに書いたバリデーションルールがdescriptionに入るのも地味に嬉しい！
ステージング環境や開発環境へデプロイする際に php artisan api:generate --routePrefix="api/*" を走らせるようにすれば、常に最新のAPIドキュメントが見られますね！
Postmanへの連携
API開発者にはお馴染みのツールPostmanですが、なんとLaravel API Documentation GeneratorはPostmanへの連携ができるようです。
先ほどのコマンドで生成された public/docs ディレクトリを見てみます。
index.htmlが先ほど見たドキュメント本体ですね。おそらく。
連携に使用するのはcollection.jsonになります。Postmanの左上の Import ボタンを押し、Import Files > Choose Filesにてcollection.jsonを指定してあげると...。
こんな風にPostmanからAPIをすぐ叩けるようになります！最高！
※気づいたらv3に上がってたので追記
なんか気づいたらv3.6が出てたので、追記します。
ドキュメント生成方法が変わったみたいですね。
$ php artisan apidoc:generate
デフォルトだとこれで自動的に routes/api.php を対象にドキュメントを生成するようですね。
で、v3から（？）設定ファイル上で生成条件を調整できるようになったみたいです。
下記のコマンドで config/apidoc.php にファイルがコピーされるので、そちらから調整できます。
$ php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config
この設定ファイルでドキュメントの生成先を変更したり、postmanのコレクションを生成するかどうか変更することができるようです。
全設定項目はこちらです。個人的にはあまり変更する必要性を感じないので、デフォルトのままで良いと思います。
まとめ
Laravel API Documentation Generatorの紹介をしました。 APIドキュメントを生成するには下記の2ステップだけでOK
1. 既存のLaravelアプリにcomposer require mpociot/laravel-apidoc-generator でLaravel API Documentation Generatorをインストール
2. php artisan api:generate --routePrefix="api/*"（v3からはこっち $ php artisan apidoc:generate）を叩いて、ドキュメント生成！
Postmanとの連携も簡単！
ぜひ使ってみてください。