l5-swaggerはインストール直後だと、OpenAPI Specification(OAS)がYAMLではなくJSONで出力されます。一般的にはYAMLで使用する機会が多いかと思いますので、今回その方法について調べました。
結論
Laravelの.envファイルに以下を記述しておけば/storage/api-docs/api-docs.yamlが生成されます。
.env
L5_SWAGGER_GENERATE_YAML_COPY=ture
ただし、あくまでJSONファイルをもとにYAMLファイルをコピーして生成する機能です。そのためJSONファイルとYAMLファイルの両方が出力されます。現状YAMLファイルだけを生成する方法はないようです。
また、YAMLからSwagger UIを表示させたい場合は、さらに追加で以下の環境変数を.envに記述します
.env
L5_FORMAT_TO_USE_FOR_DOCS=yaml
これで、Swagger UIはJSONではなくYAMLを参照してページを生成してくれるようになります。
おまけ l5-swaggerの主要なコンフィグ一覧
このあたり公式ドキュメントにもまとまっていなかったので掲載します。
app/config/l5-swagger.phpから主要なものをピックアップしましたのでご活用ください。
| 設定項目名 | 設定内容 | デフォルト値 |
|---|---|---|
| api.title | Swagger UIのブラウザタイトルを設定 | 'L5 Swagger UI' |
| routes.api | Swagger UIへのアクセスパスを設定 | 'api/documentation' |
| paths.use_absolute_path | UIのアセットに対してフルURLを使用するかどうかを設定 | true |
| paths.docs_json | 生成されるJSONドキュメンテーションファイルの名前を設定 | 'api-docs.json' |
| paths.docs_yaml | 生成されるYAMLドキュメンテーションファイルの名前を設定 | 'api-docs.yaml' |
| paths.format_to_use_for_docs | UIで使用するドキュメンテーションファイルの形式を設定 | 'json' |
| paths.annotations | Swagger注釈が格納されているディレクトリへの絶対パスを設定 | 'app' |
| securityDefinitions.securitySchemes | ドキュメントファイルに生成されるAPIセキュリティ定義の設定 | - |
| generate_always | 各リクエストでドキュメンテーションを再生成するかどうかを設定。デフォルトのfalseだとPHPDocではなくYAMLやJSONで直接記述できます | false |
| generate_yaml_copy | ドキュメンテーションをYAML形式でも生成するかどうかを設定 | false |
| proxy | プロキシのIPアドレスを信頼するかどうかを設定(AWS Load Balancer 使用時に必要) | false |
| additional_config_url | SwaggerUIBundleに渡す代わりに外部設定をフェッチするプラグインを設定 | null |
| operations_sort | 各APIの操作リストにソートを適用するかどうかを設定。 'alpha': 英数字順にパスで並べ替え。 'method': HTTP メソッドで並べ替え。 null: サーバーから変更されずに返された順序 | null |
| validator_url | JS側のSwaggerUi initにvalidatorUrlパラメータを渡すかどうかを設定 | null |
※上記表のベースはChatGPT-4に出力してもらいました。
余談
-
l5-swaggerはドキュメントがあまり多くない印象です（Githubのwikiのみ？）。これ以外にもどこかにまとまっているんですかね？知っている方いれば教えて頂きたいです！
-
OpenAPI初心者の僕は結局アノテーションでOASを書くことにすらハードルを感じてしまい、GUIでYAML定義できるStoplightに引っ越しました（SwaggerUIのためにl5-Swaggerは今も使用しています）