Laravelで作ったAPIのドキュメントを超簡単に生成する方法（Laravel API Documentation Generator）

（コメント欄まで読んでいただけると。。）

皆さんはAPIのドキュメント書いてますか？最近仕事でLaravel使ってAPIを作ったので、その仕様を他の開発者に共有しなきゃと思ったところで、そういえばドキュメント作ってなかったなーということに気づき、[swagger-php](https://github.com/zircote/swagger-php)&[Swagger UI](https://swagger.io/tools/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](https://github.com/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を追加。（すでに作ってある場合は不要）

```APIController.php
<?php

namespace App\Http\Controllers;

use App\Http\Requests\APIRequest;
use Illuminate\Http\Request;

class APIController extends Controller
{
    /**
	 * 暇を持て余した
     * 
     * 
     * 
     * 神々の
     * 
     * 
     * 
     * 遊び
	 *
	 */
    public function index(APIRequest $request)
    {
        //
    }
}

```

あと、リクエストクラスも作成。（すでに作ってある場合は不要）

```APIRequest.php
<?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に追記するのを忘れずに！

```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 へアクセスすると...

<img width="1564" alt="スクリーンショット 2018-10-20 9.44.30.png" src="https://qiita-image-store.s3.amazonaws.com/0/120969/997a0203-12d2-a44c-21fc-f24870727a75.png">

なんかできてるーーーー！！
肝心のドキュメントは...。

<img width="740" alt="スクリーンショット 2018-10-20 9.46.02.png" src="https://qiita-image-store.s3.amazonaws.com/0/120969/3479ed04-9d9f-8b15-86d6-96dcb3796429.png">

おお〜Docコメントが表示されてますね。
Requestクラスに書いたバリデーションルールがdescriptionに入るのも地味に嬉しい！
ステージング環境や開発環境へデプロイする際に `php artisan api:generate --routePrefix="api/*"` を走らせるようにすれば、常に最新のAPIドキュメントが見られますね！

### Postmanへの連携
API開発者にはお馴染みのツール[Postman](https://www.getpostman.com/)ですが、なんとLaravel API Documentation GeneratorはPostmanへの連携ができるようです。
先ほどのコマンドで生成された `public/docs` ディレクトリを見てみます。

![スクリーンショット 2018-10-20 9.18.22.png](https://qiita-image-store.s3.amazonaws.com/0/120969/733c8d3a-0e99-2244-bd0a-66a887910fa3.png)

index.htmlが先ほど見たドキュメント本体ですね。おそらく。
連携に使用するのはcollection.jsonになります。Postmanの左上の `Import` ボタンを押し、`Import Files` > `Choose Files`にてcollection.jsonを指定してあげると...。

<img width="299" alt="スクリーンショット 2018-10-20 10.01.59.png" src="https://qiita-image-store.s3.amazonaws.com/0/120969/05af1eed-afc0-ae9d-b150-d31c0f4c4c64.png">

こんな風に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のコレクションを生成するかどうか変更することができるようです。
全設定項目は[こちら](https://laravel-apidoc-generator.readthedocs.io/en/latest/config.html)です。個人的にはあまり変更する必要性を感じないので、デフォルトのままで良いと思います。

## まとめ
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との連携も簡単！
ぜひ使ってみてください。