laravel-openapiライブラリ ドキュメントを出力してみる vol1 基本的な出力

概要

• laravel-openapiを用いてルーティングとコントローラーに記載を行い最もプレーンな状態でドキュメントを出力する方法をまとめる。

前提

• 出力されたOpenAPIドキュメントは下記の方法で正しいか確認する事ができる。
  • Swagger Editorをローカルに落として開く

準備

1. 下記コマンドを実行してUserControllerクラスを作成する。

   $ php artisan make:controller UserController
   

2. 作成されたコントローラーを開き下記のように記載する。

   アプリ名ディレクトリ/app/Http/Controllers/UserController.php

   <?php
   
   namespace App\Http\Controllers;
   
   use Illuminate\Http\Request;
   
   class UserController extends Controller
   {
       /**
        * indexを返す関数
        *
        * @return void
        */
       public function index()
       {
       
       }
   }    
   

• routes/api.phpを開き下記のように記載する。

  アプリ名ディレクトリ/routes/api.php

  <?php
  
  
  use Illuminate\Support\Facades\Route;
  use App\Http\Controllers\UserController;
  
  /*
  |--------------------------------------------------------------------------
  | API Routes
  |--------------------------------------------------------------------------
  |
  | Here is where you can register API routes for your application. These
  | routes are loaded by the RouteServiceProvider within a group which
  | is assigned the "api" middleware group. Enjoy building your API!
  |
  */
  
  Route::get('/index', [UserController::class, 'index']);
  

方法

1. UserControllerを下記のように修正する。（useも忘れずに）

   アプリ名ディレクトリ/app/Http/Controllers/UserController.php

   <?php
   
   namespace App\Http\Controllers;
   
   use Illuminate\Http\Request;
   use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;
   
   #[OpenApi\PathItem]
   class UserController extends Controller
   {
       /**
        * indexを返す関数
        *
        * @return void
        */
       #[OpenApi\Operation]
       public function index()
       {
       
       }
   }
   

2. 下記コマンドを実行するとターミナルにOpenAPIのドキュメントがJSON形式で出力される。（defaultは記載しなくても勝手にデフォルト設定で出力してくれるが後々の説明のために記載）

   $ php artisan openapi:generate default
   

   {
       "openapi": "3.0.2",
       "info": {
           "title": "Laravel",
           "version": "1.0.0"
       },
       "servers": [
           {
               "url": "http:\/\/localhost"
           }
       ],
       "paths": {
           "\/api\/index": {
               "get": {
                   "summary": "indexを返す関数"
               }
           }
       }
   }
   

3. このJSON出力をファイルに出力したい場合、下記のようにリダイレクトすればファイルに出力する事ができる。

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

4. $ php artisan openapi:generate defaultコマンドの最後の引数のdefaultは「コレクション」と呼ばれる出力設定を指定している。defaultコレクションの内容はアプリ名ディレクトリ/config/openapi.phpに記載されている。（任意のコレクションを追加して呼び出す方法は別の記事で取り上げる）

   アプリ名ディレクトリ/config/openapi.php

   <?php
   
   return [
   
       'collections' => [
       
           'default' => [
           
               'info' => [
                   'title' => config('app.name'),
                   'description' => null,
                   'version' => '1.0.0',
                   'contact' => [],
               ],
           
               'servers' => [
                   [
                       'url' => env('APP_URL'),
                       'description' => null,
                       'variables' => [],
                   ],
               ],
           
               'tags' => [
               
                   // [
                   //    'name' => 'user',
                   //    'description' => 'Application users',
                   // ],
                   
               ],
           
               'security' => [
                   // GoldSpecDigital\ObjectOrientedOAS\Objects\SecurityRequirement::create()->securityScheme('JWT'),
               ],
           
               // Route for exposing specification.
               // Leave uri null to disable.
               'route' => [
                   'uri' => '/openapi',
                   'middleware' => [],
               ],
           
               // Register custom middlewares for different objects.
               'middlewares' => [
                   'paths' => [
                       //
                   ],
                   'components' => [
                       //
                   ],
               ],
           
           ],
       
       ],
   
       // Directories to use for locating OpenAPI object definitions.
       'locations' => [
           'callbacks' => [
               app_path('OpenApi/Callbacks'),
           ],
       
           'request_bodies' => [
               app_path('OpenApi/RequestBodies'),
           ],
       
           'responses' => [
               app_path('OpenApi/Responses'),
           ],
       
           'schemas' => [
               app_path('OpenApi/Schemas'),
           ],
       
           'security_schemes' => [
               app_path('OpenApi/SecuritySchemes'),
           ],
       ],
   
   ];
   

参考文献

• https://vyuldashev.github.io/laravel-openapi/