laravel-openapiを使ってみる 本当に触りだけ

概要

• laravel-openapiというライブラリを使ってみたので使った時のメモと導入方法を残す。

できるようになること

• routes/直下やapp/Http/Controllers/直下を見に行って勝手にOpenApiのフォーマットのドキュメントを出力してくれる。

導入方法

1. 下記コマンドを実行してライブラリをインストールする。

   $ composer require vyuldashev/laravel-openapi
   

2. config/app.phpを開き、providersの配列に下記の様に追記を行う。

   config/app.php

   'providers' => [
       /*
        * Package Service Providers...
        */
       Vyuldashev\LaravelOpenApi\OpenApiServiceProvider::class,
   ];
   

3. 下記コマンドを実行して設定ファイルを生成する。（config/直下にlaravel-openapi専用の設定ファイルがvendor/直下のライブラリのディレクトリからコピーされて作成される。）

   $ php artisan vendor:publish --provider="Vyuldashev\LaravelOpenApi\OpenApiServiceProvider" --tag="openapi-config"
   

準備

1. 下記コマンドを実行してContentController.phpを作成する。

   $ php artisan make:controller ContentController
   

2. 作成されたContentController.phpに下記の様に修正する。（Requestをそのまま帰すだけの関数を定義）

   app/Http/Controllers/ContentController.php

   <?php
   
   namespace App\Http\Controllers;
   
   use Illuminate\Http\Request;
   use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;
   
   #[OpenApi\PathItem]
   class ContentController extends Controller
   {
       /**
        * リクエストをそのまま帰す
        *
        * @param Request $request
        * @return Request
        */
       #[OpenApi\Operation]
       public function index(Request $request) : Request
       {
           return $request;
       }
   }
   

3. routes/api.phpを下記のように記載して先に作成したコントローラーの関数へのルーティングを定義する。

   routes/api.php

   use App\Http\Controllers\ContentController;
   
   Route::get('/content/index',[ContentController::class, 'index']);
   

使ってみる

1. 下記コマンドを実行して先に登録したAPIルーティングをOpenApiのフォーマットでターミナルに出力する。

   $ php artisan openapi:generate
   

2. 下記のように出力された。

   openapi.json

   {
       "openapi": "3.0.2",
       "info": {
           "title": "Laravel",
           "version": "1.0.0"
       },
       "servers": [
           {
               "url": "http:\/\/localhost"
           }
       ],
       "paths": {
           "\/api\/content\/index": {
               "get": {
                   "summary": "リクエストをそのまま帰す"
               }
           }
       }
   }
   

3. ターミナルに出力されたOpenApiのフォーマットのAPI情報をファイルに出力したい場合は下記のようにすればファイルに出力する事ができる。（$ php artisan openapi:generateコマンド実行してもjsonファイルは出力されないですよね・・・？）

   $ php artisan openapi:generate > OpenApi形式でAPI情報を出力するファイル名.json
   

参考文献

• 公式ドキュメント
• Github