laravel-apidoc-generator 導入メモ

morishita

LaravelでAPI開発をするに当たり、APIドキュメントを楽に生成できないかなーと調べてみたところ、
laravel-apidoc-generatorというツールにたどり着きました。

ここでは導入手順と自分が行った設定、簡単な使用方法を備忘録として記載します。

▼ドキュメント
Document

▼github
laravel-apidoc-generator

１．導入手順・生成コマンド

公式の手順通り、以下コマンドでインストールします。

composer require mpociot/laravel-apidoc-generator
php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

生成コマンドは以下です。
更新する時には都度このコマンドで生成するイメージです。

php artisan apidoc:generate

デフォルトでpublic/doc以下にファイルが生成されるので、以下URLで参照できます。

ルートURL/public/docs/index.html

以下の様にドキュメントが生成されます。

２．設定

私が導入した際に設定した内容をまとめます。

設定するファイルは以下です。

/config/apidoc.php

①生成するAPIのrouteパターンを指定

たとえばURLに「api/v1/」を含むAPIのみを対象としたい場合、apidoc.phpに以下の様に記述します。
（執筆時点では、apidoc.phpの112行目あたりです。）

'routes' => [
    [
        'match' => [
            'prefixes' => [
                'api/v1/*',
            ],
        ]
    ]
]

※構成が分かりやすいように、必要な箇所のみ抽出しています。
※公式ドキュメントのリンク ⇒ リンク

②レスポンスを自動生成

デフォルトではレスポンスのドキュメントは自動生成されず、自分で記載する必要があります。
後述しますが、コメントでJsonを都度記載するのはかなり手間なので、この設定を探したところ以下に有りました。
（執筆時点では、apidoc.phpの167行目あたりです。）

'routes' => [
    [
        'apply' => [
            'response_calls' => [
                'methods' => ['*'],
            ]
        ]
    ]
]

methodsの項目で、レスポンスを自動生成するメソッドを指定できるみたいです。
細かい使い方はわからないですが、全て自動生成にしたかったので「*」にしました。
個人的にすごく便利だと思うので、デフォルトで設定されてると親切なのに‥と思いました。

※構成が分かりやすいように、必要な箇所のみ抽出しています。
※公式ドキュメントのリンク ⇒ リンク

３．ドキュメント記載方法

ドキュメントを記述するには、対象のアクションに指定のフォーマットでコメントを書きます。
何パターンかテンプレみたいな感じで紹介します。

①GETのAPI（レスポンス記載Ver.）

route/api.phpは以下。

$router->get('/v1/sample01', 'Api\V1\SampleController@sample01');

※「app/Http/Controllers/Api/V1」以下にコントローラーを配置しています。

SampleController.php

    /**
     * @group Sample
     * [001]GETのサンプル
     * API作成のサンプル。
     * valに10を掛けた値を返します。
     * 
     * @queryParam val required valの値 Example: 10
     * 
     * @response {
     *   "result": 100
     * }
     */
    public function sample01(Request $req){

        $response["result"] = $req->val * 10;

        return response($response);
    }

以下のようなドキュメントが生成されます。

このパターンは丁寧に「@response」を記載していますが、手順２．でレスポンス自動生成の設定をしていれば不要な項目です。
というかこれを書くのが面倒だったので設定を入れたという経緯です。
以下に紹介します。

②GETのAPI（レスポンス自動Ver.）

SampleController.php

    /**
     * @group Sample
     * [001]GETのサンプル
     * API作成のサンプル。
     * valに10を掛けた値を返します。
     * 
     * @queryParam val required valの値 Example: 10
     */
    public function sample01(Request $req){

        $response["result"] = $req->val * 10;

        return response($response);
    }

「@response」の項目だけ省略した形です。
改めでドキュメントを生成して、同様のページが生成されていればOKです。

③POSTのAPI（レスポンス自動Ver.）

route/api.phpは以下。

$router->post('/v1/sample02', 'Api\V1\SampleController@sample02');

SampleController.php

    /**
     * @group Sample
     * [002]POSTのサンプル
     * API作成のサンプル。
     * valに10を掛けた値を返します。
     * 
     * @bodyParam val int required valの値 Example: 10
     */
    public function sample02(Request $req){

        $response["result"] = $req->val * 10;

        return response($response);
    }

GETの場合と異なるのは、「@queryParam」から「@bodyParam」に変わっている点です。
また、bodyParamの場合にはTypeを指定できる（指定しないとズレる）ので、「int」を指定しています。