概要

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

前提

下記記事の内容が完了しているものとする。
- laravel-openapi ドキュメントを出力してみる vol1 基本的な出力
出力されたOpenAPIドキュメントは下記の方法で正しいか確認する事ができる。
- Swagger Editorをローカルに落として開く
下記の内容を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()
{

}
```

方法

ルートパラメーター

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

クエリパラメーター

クエリパラメーターは開発者が定義して上げる必要がある。
下記コマンドを実行してクエリパラメーターを定義するクラスを作成する。
```
$ php artisan openapi:make-parameters UserQuery
```
アプリ名ディレクトリ/app/OpenApi/Parameters直下にUserQueryParameters.phpが作成されるので開く

下記のようにUserQueryParametersクラスの中のbuild関数の中に追記してクエリパラメーターの情報を指定する。（筆者は出力を試したいだけなのでUserQueryParameters.phpを出力したまんまの状態で特に記載変更していない。）

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

定義したクエリパラメーターを/user/{user_id}のGETメソッドのルーティングに紐づけてみる。

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()
    {
    
    }
}

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

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

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

{
    "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/