OAS 2 此页面适用于 OpenAPI 规范版本 2（以前称为 Swagger）。要了解最新版本，请访问 OpenAPI 3 页面。

API 密钥

某些 API 使用 API 密钥进行授权。API 密钥是客户端在进行 API 调用时需要提供的特殊令牌。密钥通常作为请求标头发送

GET /something HTTP/1.1
X-API-Key: abcdef12345

或作为查询参数发送

GET /something?api_key=abcdef12345

API 密钥应该是只有客户端和服务器知道的秘密。但是，与基本身份验证一样，基于 API 密钥的身份验证不被认为是安全的，除非与其他安全机制（例如 HTTPS/SSL）一起使用。

要定义基于 API 密钥的安全

• 在全局 securityDefinitions 部分中添加一个 type: apiKey 的条目。条目名称可以是任意的（例如，下面的示例中的 APIKeyHeader），并用于从规范的其他部分引用此安全定义。
• 指定 API 密钥是否将传递 in: header 或 in: query。
• 为该参数或标头指定一个 name。

securityDefinitions:
   # X-API-Key: abcdef12345
   APIKeyHeader:
     type: apiKey
     in: header
     name: X-API-Key
   # /path?api_key=abcdef12345
   APIKeyQueryParam:
     type: apiKey
     in: query
     name: api_key

然后，在根级别或操作级别使用 security 部分将 API 密钥应用于整个 API 或特定操作。

# Global security (applies to all operations):
security:
  - APIKeyHeader: []
paths:
  /something:
    get:
      # Operation-specific security:
      security:
        - APIKeyQueryParam: []
      responses:
        200:
          description: OK (successfully authenticated)

请注意，可以在 API 中支持多种授权类型。请参阅 使用多种身份验证类型。

API 密钥对

某些 API 使用一对安全密钥，例如 API 密钥和应用程序 ID。要指定这些密钥一起使用（逻辑 AND），请在 security 数组中的同一数组项中列出它们

securityDefinitions:
  apiKey:
    type: apiKey
    in: header
    name: X-API-KEY
  appId:
    type: apiKey
    in: header
    name: X-APP-ID
security:
  - apiKey: []
    appId: []

注意与

security:
  - apiKey: []
  - appId: []

的不同之处，这意味着可以使用任何一个密钥（逻辑 OR）。有关更多示例，请参阅 使用多种身份验证类型。

401 响应

您还可以定义对缺少或无效 API 密钥的请求返回的 401“未授权”响应。此响应包括 WWW-Authenticate 标头，您可能想要提及它。与其他常见响应一样，可以全局 responses 部分定义 401 响应，并从多个操作中引用。

paths:
  /something:
    get:
      ...
      responses:
        ...
        401:
           $ref: '#/responses/UnauthorizedError'
    post:
      ...
      responses:
        ...
        401:
          $ref: '#/responses/UnauthorizedError'
responses:
  UnauthorizedError:
    description: API key is missing or invalid
    headers:
      WWW_Authenticate:
        type: string

  

没有找到您要找的内容？ 询问社区
发现错误？ 告诉我们