説明
OpenAPI 3.0の操作にあるsecurityの名前は、components.securitySchemesに定義する必要があります。操作ごとのsecurityはグローバルな要件を上書きするため、その操作に必要な認証方式を正しく指定してください。
想定される影響
ツールやAPI利用者が操作の認証要件を誤解し、呼び出しに失敗する場合があります。文書の誤りが、そのままサーバーの認証回避を意味するわけではありません。
対処方法
操作が参照するスキームを同じ名前で定義し、認証方式とスコープを確認してください。OAuth2とOpenID Connect以外の方式では、スコープの配列を空にしてください。操作に実際に適用される認証も確認してください。
例
GET操作の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",
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
],
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"operationId": "listVersionsv2",
"summary": "List API versions",
"security": [
{
"petstore_auth": [
"write:pets",
"read:pets"
]
}
],
"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"
}
]
}
]
}
}
}
}
}
}
}
}
}
},
"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"
}
}
}
}
}
}
変更後は、GET操作のセキュリティ要件が定義済みのpetstore_authを参照します。スキームの定義と、サーバーが受信したリクエストを認証する処理は別です。