説明
OpenAPI 3.0のグローバルなsecurityで使う名前は、components.securitySchemesに定義する必要があります。名前が一致しないと、API利用者が必要な認証方式を確認しにくくなります。
想定される影響
ドキュメントツールやクライアント生成ツールが認証設定を解釈できない場合があります。文書の参照エラーだけで、サーバーの認証が無効だとは判断できません。
対処方法
参照と同じ名前でセキュリティスキームを定義し、実際の認証方式に合わせて設定してください。OAuth2とOpenID Connectではスコープの一覧を確認し、他の認証方式では空の配列を使ってください。サーバー側の認証適用も別途確認してください。
例
グローバルなpetstore_auth参照に定義を追加する例です。含まれるimplicitフローとHTTPの認可URLは過去の形式であり、本番環境への推奨構成ではありません。新しいOAuth2構成では、HTTPSとPKCEを伴う認可コードフローを検討してください。
変更前
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
]
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"examples": {
"foo": {
"value": {
"versions": [
{
"status": "CURRENT",
"updated": "2011-01-21T11:33:21Z",
"id": "v2.0",
"links": [
{
"href": "http://127.0.0.1:8774/v2/",
"rel": "self"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
],
"components": {
"securitySchemes": {
"regularSecurity": {
"type": "http",
"scheme": "basic"
},
"petstore_auth": {
"type": "oauth2",
"flows": {
"implicit": {
"scopes": {
"write:pets": "modify pets in your account",
"read:pets": "read your pets"
},
"authorizationUrl": "http://example.org/api/oauth/dialog"
}
}
}
}
}
}
変更後はpetstore_authの定義を参照できます。別に定義されたregularSecurityは、このsecurity項目では選択されていません。文書の変更だけでサーバーに認証が適用されるわけではありません。