【OpenAPI】OpenAPIを使ってマッピング設定を行う

2025年1月13日OpenAPI,Other

今回はOpenAPIを使ってマッピング設定を行う紹介です。
OpenAPIとLaravelを使っていきます。

1. OpenAPIを使ってマッピング設定とは？
2. OpenAPI
3. OpenAPIでよく使われるキー
4. config/openapi
5. Controller

OpenAPIを使ってマッピング設定とは？

OpenAPIを使用したLaravelアプリケーションのAPI設定方法と、コントローラーへのマッピング手法について解説します。
この設定により、API仕様の管理と実装の整合性を確保できます。

OpenAPI

OpenAPIの説明はこちらを参考にしてみてください。

operationIdがControllerと紐付け後で行います。

# openapi.yml
openapi: 3.0.0
paths:
 /api/users:
   get:
     operationId: user#list
     responses:
       '200':
         content:
           application/json:
             schema:
               type: array
               items:
                 $ref: '#/components/schemas/User'

 /api/users/{id}:
   get:
     operationId: user#get
     parameters:
       - name: id
         in: path
         required: true
         schema:
           type: integer
     responses:
       '200':
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/User'

components:
 schemas:
   User:
     type: object
     properties:
       id:
         type: integer
       name:
         type: string

スポンサードサーチ

OpenAPIでよく使われるキー

OpenAPIでよく使われるキーの一覧です。

余談ではありますが、次に出てくるので、覚えておきましょう。

return [
    'spec' => '仕様書の場所',
    'validate_responses' => '検証フラグ',
    'paths' => 'APIパス定義',
    'securities' => '認証設定',
    'servers' => 'サーバー設定',
    'middleware' => 'ミドルウェア設定'
];

config/openapi

LaravelのOpenAPI設定ファイルの詳細解説します。
「config/openapi」ファイルを読み込むことで、OpenAPIとControllerを紐づけてます。

<?php

return [
    'spec' => base_path(env('API_PATH', 'openapi/openapi.yml')),
    'validate_responses' => env('API_VALIDATE_RESPONSES', true),
    'operationIdMap' => [
        'api' => [
            'user#get' => 'UserController@get',
            'user#list' => 'UserController@list',
        ],
    ],
];

各行細かく説明しますね

'spec' => base_path(env('API_PATH', 'openapi/openapi.yml')),

base_path(): Laravelのルートディレクトリからの相対パスを指定
env('API_PATH’, …): 環境変数から設定を読み込みます
デフォルト値は 'openapi/openapi.yml’です

'validate_responses' => env('API_VALIDATE_RESPONSES', true),

APIレスポンスがOpenAPI仕様に準拠しているか検証します。
環境変数で制御可能（開発環境での使用を推奨）しており
デフォルトは有効（true）です。

'operationIdMap' => [
    'api' => [
        'user#get' => 'UserController@get',
        'user#list' => 'UserController@list',
    ],
],

operationIdとContollerとメソッドが紐づいています

OpenAPI仕様のoperationIdとコントローラーメソッドの紐付け
形式: 'operationId’ => 'コントローラー名@メソッド名’
'api’グループ配下にマッピングを定義

スポンサードサーチ

Controller

コントローラーとメソッドはあくまでもサンプルとしてみてください。
今回は「config/openapi」を使って「openapi.yml」とContollerを紐づける設定についてなので、省略します。

// UserController.php
class UserController extends Controller 
{
    public function list()
    {
        $users = User::all();
        return response()->json($users);
    }

    public function get($id) 
    {
        $user = User::findOrFail($id);
        return response()->json($user);
    }
}