前提
ドメインに応じて生成するSwaggerドキュメントを分けたい
今まではhoge.com向け一本でSwaggerドキュメント（型定義）を生成していたが、
fuga.hoge.com向けに、今までの型定義と分けて、別途で型定義を生成したい。
ここでドキュメントを分ける理由は、今までのと合わせて生成するのでは単純に見分けがつきづらいのと、
分けて生成することで、それぞれのドキュメントが不要に肥大化するのを避けるため。
使用ライブラリ
L5-swagger
https://github.com/DarkaOnLine/L5-Swagger
内容
基本的な使用方法
インストール
一通りのインストール方法については、こちらに記載がある
https://github.com/DarkaOnLine/L5-Swagger/wiki/Installation-&-Configuration
L5-swaggerが提供するUIで型定義を確認する方法についても記載があるが、
弊環境では必要としておらず、最低限、型定義のjsonファイルを出力すればよかったため、
以下にはその最低限の部分のみ記載する。
terminal.
composer require "darkaonline/l5-swagger"
AppServiceProvider.php > register
$this->app->register(\L5Swagger\L5SwaggerServiceProvider::class);
型定義の生成
型定義を生成させるためのアノテーション作成
何かしらのController.php
/**
* 今まで通りのPHPDoc
* @OA\Post (
* path="/api/hoge",
* operationId="HogeMethod",
* tags={"hoge"},
* summary="サンプル：ホゲホゲ",
* description="ホゲホゲするメソッド",
* security={{}},
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(ref="#/components/schemas/HogeHogeRequest"),
* )
* ),
* @OA\Response(response=200, ref="#/components/responses/200"),
* )
*/
public function hoge(HogeHogeRequest $request)
{
return 200;
}
@OA\Post以下が、L5-swaggerで型定義を生成するためのアノテーションです。
（サンプルで色々書いてますが、あくまで個人の環境に合わせてください）
型定義を生成するコマンド
terminal.
php artisan l5-swagger:generate
今回やったこと
config/l5-swagger.phpファイルを編集し、サブドメインごとに
型定義を出力できるように調整。
具体的なやりかた
デフォルトのconfigファイル（一部コメント等を割愛しています）
config/l5-swagger.php
<?php
return [
'default' => 'default',
'documentations' => [
'default' => [
'api' => [
'title' => 'L5 Swagger UI',
],
'routes' => [
'api' => 'api/documentation',
],
'paths' => [
~~~
'docs_json' => 'api-docs.json',
~~~
'annotations' => [
base_path('app'),
],
],
],
],
'defaults' => [
'routes' => [
'docs' => 'docs',
~~~
],
'paths' => [
~~~
],
サブドメインごとにファイルを分けたいよ。というのを書いてあげる
↓
config/l5-swagger.php
<?php
return [
'default' => 'default',
// 追加したい（A => Aとなってれば命名は何でもOK）
'hoge_subdomain' => 'hoge_subdomain',
'documentations' => [
'default' => [
'api' => [
'title' => 'L5 Swagger UI',
],
'routes' => [
'api' => 'api/documentation',
],
'paths' => [
~~~
'docs_json' => 'api-docs.json',
~~~
'annotations' => [
base_path('app'),
],
],
],
// ↑で追加したのと同名で配列を作成する
'hoge_subdomain' => [
'api' => [
'title' => 'L5 HogeHoge UI',
],
'routes' => [
'api' => 'hoge_subdomain/documentation',
],
'paths' => [
~~~
'docs_json' => 'api-docs-hoge_subdomain.json',
~~~
'annotations' => [
base_path('app'),
],
],
],
],
'defaults' => [
'routes' => [
'docs' => 'docs',
~~~
],
'paths' => [
~~~
],
型定義生成コマンド
terminal.
php artisan l5-swagger:generate --all
実行結果.
Regenerating docs default
Regenerating docs hoge_subdomain
これで、サブドメインごとに出力する型定義を切り替えられるようになります。