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は今も使用しています）