基本认证

基本认证是一种内置于 HTTP 协议的简单认证方案。客户端发送带有 Authorization 头的 HTTP 请求，该头包含单词 Basic，后跟一个空格和 base64 编码的字符串 username:password。例如，要以 demo / p@55w0rd 身份进行认证，客户端将发送

1
Authorization: Basic ZGVtbzpwQDU1dzByZA==

注意：由于 base64 很容易解码，基本认证应仅与其他安全机制（如 HTTPS/SSL）一起使用。

描述基本认证

使用 OpenAPI 3.0，您可以按如下方式描述基本认证：

1
openapi: 3.0.4
2
---
3
components:
4
  securitySchemes:
5
    basicAuth: # <-- arbitrary name for the security scheme
6
      type: http
7
      scheme: basic
8

9
security:
10
  - basicAuth: [] # <-- use the same name here

第一部分 securitySchemes 定义了一个名为 basicAuth（任意名称）的安全方案。该方案必须具有 type: http 和 scheme: basic。然后，security 部分将基本认证应用于整个 API。方括号 [] 表示使用的安全范围；该列表为空，因为基本认证不使用范围。security 可以全局设置（如上例所示）或在操作级别设置。如果只有一部分操作需要基本认证，则后者会很有用。

1
paths:
2
  /something:
3
    get:
4
      security:
5
        - basicAuth: []

基本认证也可以与其他认证方法结合使用，如使用多种认证类型中所述。

401 响应

您还可以定义因凭据缺失或不正确而返回的 401“未授权”响应。此响应包含您可能希望提及的 WWW-Authenticate 头。与其他常见响应一样，401 响应可以在全局 components/responses 部分中定义，并通过 $ref 在其他地方引用。

1
paths:
2
  /something:
3
    get:
4
      ...
5
      responses:
6
        ...
7
        '401':
8
            $ref: '#/components/responses/UnauthorizedError'
9
    post:
10
      ...
11
      responses:
12
        ...
13
        '401':
14
          $ref: '#/components/responses/UnauthorizedError'
15
...
16
components:
17
  responses:
18
    UnauthorizedError:
19
      description: Authentication information is missing or invalid
20
      headers:
21
        WWW_Authenticate:
22
          schema:
23
            type: string

要了解有关 responses 语法的更多信息，请参阅描述响应。

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