OpenAPI 3.0中如何指定认证URL？以及如何在Bearer认证方案中告知用户Token获取方式并处理全局安全属性？

好问题！这确实是OpenAPI 3.0里Bearer认证文档化时容易遇到的细节点，我来给你一步步梳理清楚：

一、如何明确Token获取方法，同时合理处理安全属性 #

你推测的“移除全局安全属性，转而给除认证端点外的所有端点加安全属性”是可行的，但其实有更高效的做法：保留全局安全属性，给认证端点单独设置跳过认证，这样其他端点自动继承全局的Bearer认证要求，只有认证端点可以无权限访问，不用逐个配置。

示例代码如下：

openapi: 3.0.3
info:
  title: 你的API文档
  version: 1.0.0

# 全局安全属性：所有端点默认需要bearerToken认证
security:
  - bearerToken: []

components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      description: "使用本API需提供Token，您可通过向`/api/auth`发送POST请求，传入`login`和`password`字段来获取Token"

paths:
  # 认证端点：用security: []覆盖全局要求，无需认证即可访问
  /api/auth:
    post:
      summary: 获取Bearer Token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                login:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: 成功获取Token
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

  # 其他需要认证的端点：自动继承全局security设置，无需重复配置
  /api/users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表

这样既把认证端点明确加入了文档，又省去了逐个给其他端点添加安全属性的麻烦。

二、如何在OpenAPI 3.0中指定认证URL #

OpenAPI 3.0的http类型Bearer认证方案本身没有专门的tokenUrl字段（这个字段是OAuth2专用的），但我们有两种清晰的方式来指定Token获取URL：

• 方式一：在securitySchemes的描述里直接说明
  就像上面示例里的description字段，直接把获取Token的端点和方法写进去，用户查看认证方案时就能一眼看到关键信息。
• 方式二：在认证端点的文档里详细定义
  把/api/auth的请求体结构、参数要求、响应示例都写清楚，用户在浏览API端点列表时，能直观找到获取Token的完整操作流程。

两种方式结合使用效果最好，既在认证方案里做了提示，又在具体端点里提供了完整的操作指南。

内容的提问来源于stack exchange，提问作者sylbru