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

概要

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

方法

ルートパラメーター

1. laravel-openapiは二種類あるパラメーター（ルートとクエリ）のうち、URLに含まれるルートパラメーターはOpenAPI出力時に勝手にroutes/api.phpを読みに行ってパラメーター情報を出力してくれる。

2. 「前提」にて既にルートパラメーター付きのルーティングとコントローラークラスの関数の定義が完了しているので下記コマンドを実行してOpenAPIを出力してみる。

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

3. 下記のように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. クエリパラメーターは開発者が定義して上げる必要がある。

2. 下記コマンドを実行してクエリパラメーターを定義するクラスを作成する。

   $ php artisan openapi:make-parameters UserQuery
   

3. アプリ名ディレクトリ/app/OpenApi/Parameters直下にUserQueryParameters.phpが作成されるので開く

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

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

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

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

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

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

8. 下記のように出力され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/