OpenAPI3.0ではservers
に複数のURLを設定することで、Swagger UIでローカル/開発/本番環などリクエスト先を切り替えることができます。
openapi: 3.0.0
info:
description: サンプルAPI
version: 1.0.0
title: Sample API
servers:
- url: http://localhost:8000
description: ローカル開発環境
- url: https://dev.api.com
description: 開発環境
- url: https://api.com
description: 本番環境
また、OAuth2.0で認証が必要な場合はauthorizationCode
に認可エンドポイントとトークンエンドポイントを設定することで、Swagger UIがOAuth認証のメニューを生成してくれます。
(次のコードは認可コードフローの例です。)
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://api.com/auth
tokenUrl: https://api.com/token
authorizationCode
についてもservers
と同じように複数環境分を設定し、それがserversと一緒に切り替わってくれることを期待したのですが、authorizationCode
は複数の環境に対応しておらず、単に次のように列挙するだけではエラーになってしまいます。
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: http://localhost:8000/auth
tokenUrl: https://localhost:8000/token
authorizationCode:
authorizationUrl: https://dev.api.com/auth
tokenUrl: https://dev.api.com/token
authorizationCode:
authorizationUrl: https://api.com/auth
tokenUrl: https://api.com/token
このような場合は、authorizationCode
をドメインからの相対パスで書くことで解決できます。
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: /auth
tokenUrl: /token
authorizationCode
はセキュリティ上の問題からパラメータの埋め込みには対応していないようなので(参考)、環境ごとに認可・トークンエンドポイントが異なる場合は現状手立てがなく、authorizationCodeを毎回書き換えるしかなさそうです。