.NET 9中如何配置Scalar仅对外部控制器请求API Key？

核心思路是通过OpenAPI规范的安全方案定义+路径级安全要求，让Scalar自动识别不同控制器的认证规则，实现仅外部控制器要求API Key的效果。

步骤1：在OpenAPI文档中定义两种安全方案 #

首先在你的OpenAPI规范（YAML/JSON）里，明确JWT和API Key两种认证方式：

components:
  securitySchemes:
    # 内部控制器用的JWT认证
    InternalJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
    # 外部控制器用的API Key认证
    ExternalAPIKey:
      type: apiKey
      in: header
      name: X-API-Key  # 自定义的API Key请求头名称

步骤2：给不同控制器的路径绑定对应安全要求 #

针对内部、外部控制器的接口路径，分别指定对应的安全规则：

内部控制器路径（仅要求JWT） #

paths:
  /internal/users:
    get:
      summary: 获取内部用户列表
      security:
        - InternalJWT: []  # 绑定JWT安全方案
      responses:
        '200':
          description: 返回用户列表

外部控制器路径（仅要求API Key） #

/external/public-data:
    get:
      summary: 获取公开数据
      security:
        - ExternalAPIKey: []  # 绑定API Key安全方案
      responses:
        '200':
          description: 返回公开数据

如果你的框架支持自动生成OpenAPI文档（比如Spring Boot、Node.js），可以通过注解/注释给控制器绑定安全要求：

Spring Boot（SpringDoc示例）

• 内部控制器类添加注解：

  @RestController
  @RequestMapping("/internal")
  @SecurityRequirement(name = "InternalJWT")
  public class InternalUserController {
      // 接口逻辑
  }
  

• 外部控制器类添加注解：

  @RestController
  @RequestMapping("/external")
  @SecurityRequirement(name = "ExternalAPIKey")
  public class ExternalDataController {
      // 接口逻辑
  }
  

Node.js（Express + swagger-jsdoc示例）

在外部路由的Swagger注释里指定安全要求：

/**
 * @swagger
 * /external/public-data:
 *   get:
 *     summary: 获取公开数据
 *     security:
 *       - ExternalAPIKey: []
 *     responses:
 *       200:
 *         description: 成功返回数据
 */
app.get('/external/public-data', (req, res) => {
  // 业务逻辑
});

步骤3：启动Scalar并指向你的OpenAPI文档 #

启动Scalar时，传入你的OpenAPI文档地址（比如本地API的文档端点）：

scalar openapi http://localhost:8080/v3/api-docs

Scalar会自动解析每个路径的安全要求：

• 调试内部控制器接口时，Scalar会提示输入JWT令牌
• 调试外部控制器接口时，只会提示输入API Key（X-API-Key）

可选：设置全局默认认证（按需覆盖） #

如果大部分接口是内部JWT，仅少数外部接口用API Key，可以在OpenAPI根级别设置全局默认安全方案，再给外部路径单独覆盖：

# 全局默认用JWT认证
security:
  - InternalJWT: []

paths:
  /internal/users:
    get: ...  # 继承全局JWT规则
  /external/public-data:
    get:
      security:
        - ExternalAPIKey: []  # 覆盖全局，使用API Key

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