laravel-openapiライブラリ ドキュメントを出力してみる 番外編 パラメーター

# 概要

- laravel-openapiにてパラメーターを定義・設定する方法をまとめる。

# 前提

- 下記記事の内容が完了しているものとする。
    - [laravel-openapi ドキュメントを出力してみる vol1 基本的な出力](https://qiita.com/miriwo/items/2c8dcbefdde338ce62a9)
- 出力されたOpenAPIドキュメントは下記の方法で正しいか確認する事ができる。
    - [Swagger Editorをローカルに落として開く](https://qiita.com/miriwo/items/93a845f03435fbbce3bd)
- 下記の内容を`routes/api.php`に追記する。

    ```アプリ名ディレクトリ/routes/api.php
    Route::get('/user/{user_id}', [UserController::class, 'detail']);
    ```

- 下記の関数をUserController.phpに追記する。

    ```アプリ名ディレクトリ/app/Http/Controllers/UserController.php
    /**
     * ユーザー詳細を返す関数
     *
     * @return void
     */
    #[OpenApi\Operation]
    public function detail()
    {

    }
    ```

# 方法

### ルートパラメーター

1. laravel-openapiは二種類あるパラメーター（ルートとクエリ）のうち、URLに含まれるルートパラメーターはOpenAPI出力時に勝手にroutes/api.phpを読みに行ってパラメーター情報を出力してくれる。
1. 「前提」にて既にルートパラメーター付きのルーティングとコントローラークラスの関数の定義が完了しているので下記コマンドを実行してOpenAPIを出力してみる。

    ```terminal
    $ php artisan openapi:generate default > storage/openapi.json
    ```

1. 下記のようにJSONが出力されたのでルートパラメーターはルーティングに定義するだけで自動でドキュメント化してくれる。

    ```json
    {
        "openapi": "3.0.2",
        "info": {
            "title": "Laravel",
            "version": "1.0.0"
        },
        "servers": [
            {
                "url": "http:\/\/localhost"
            }
        ],
        "paths": {
            "\/api\/index": {
                "get": {
                    "summary": "indexを返す関数"
                }
            },
            "\/api\/user\/{user_id}": {
                "get": {
                    "summary": "ユーザー詳細を返す関数",
                    "parameters": [
                        {
                            "name": "user_id",
                            "in": "path",
                            "required": true,
                            "schema": {
                                "type": "string"
                            }
                        }
                    ]
                }
            }
        }
    }
    ```

### クエリパラメーター

1. クエリパラメーターは開発者が定義して上げる必要がある。
1. 下記コマンドを実行してクエリパラメーターを定義するクラスを作成する。

    ```temrinal
    $ php artisan openapi:make-parameters UserQuery
    ```

1. `アプリ名ディレクトリ/app/OpenApi/Parameters`直下に`UserQueryParameters.php`が作成されるので開く
1. 下記のように`UserQueryParameters`クラスの中のbuild関数の中に追記してクエリパラメーターの情報を指定する。（筆者は出力を試したいだけなのでUserQueryParameters.phpを出力したまんまの状態で特に記載変更していない。）

    | 関数名 | 内容 | 概要 |
    | --- | --- | --- |
    | name | クエリパラメーターのキー名 |  |
    | description | クエリパラメーターの説明 |  |
    | required | パラメーターが必須かどうか | true：必須 false:任意 |
    | schema | データ型 | `Schema::string()`のように<br>Schemaクラスの型を表す関数を静的呼び出しして指定 |

1. 定義したクエリパラメーターを`/user/{user_id}`のGETメソッドのルーティングに紐づけてみる。
1. UserController.phpを開き下記のように修正する。（useも忘れずに）

    ```アプリ名ディレクトリ/app/Http/Controllers/UserController.php
    <?php
    
    namespace App\Http\Controllers;
    
    use App\OpenApi\Parameters\UserQueryParameters;
    use Illuminate\Http\Request;
    use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;
    
    #[OpenApi\PathItem]
    class UserController extends Controller
    {
        /**
         * indexを返す関数
         *
         * @return void
         */
        #[OpenApi\Operation]
        public function index()
        {
        
        }
    
        /**
         * ユーザー詳細を返す関数
         *
         * @return void
         */
        #[OpenApi\Operation]
        #[OpenApi\Parameters(UserQueryParameters::class)]
        public function detail()
        {
        
        }
    }
    ```

1. 下記コマンドを実行してOpenAPIを出力してみる。

    ```terminal
    $ php artisan openapi:generate default > storage/openapi.json
    ```

1. 下記のように出力されparametersオブジェクトにUserQueryParameters.phpで定義したものが追加されている事がわかる。

    ```json
    {
        "openapi": "3.0.2",
        "info": {
            "title": "Laravel",
            "version": "1.0.0"
        },
        "servers": [
            {
                "url": "http:\/\/localhost"
            }
        ],
        "paths": {
            "\/api\/index": {
                "get": {
                    "summary": "indexを返す関数"
                }
            },
            "\/api\/user\/{user_id}": {
                "get": {
                    "summary": "ユーザー詳細を返す関数",
                    "parameters": [
                        {
                            "name": "user_id",
                            "in": "path",
                            "required": true,
                            "schema": {
                                "type": "string"
                            }
                        },
                        {
                            "name": "parameter-name",
                            "in": "query",
                            "description": "Parameter description",
                            "required": false,
                            "schema": {
                                "type": "string"
                            }
                        }
                    ]
                }
            }
        }
    }
    ```

# 参考文献

- [https://vyuldashev.github.io/laravel-openapi/](https://vyuldashev.github.io/laravel-openapi/)