如何让NSwagStudio自动生成带[Authorize]特性的C#控制器

问题翻译 #

我正在使用NSwagStudio开发API，希望自动生成的C#控制器代码中包含[Authorize(Roles = "User")]特性，目标生成代码如下：

/// <summary>
/// Returns a list of Things.
/// </summary>
/// <returns>A JSON array of Things</returns>
[Microsoft.AspNetCore.Mvc.HttpGet, Microsoft.AspNetCore.Mvc.Route("Thing", Name = "Thing"), Authorize(Roles = "User")]
public System.Threading.Tasks.Task<System.Collections.Generic.ICollection<Thing>> Machine()
{
    return _implementation.ThingAsync();
}

目前手动添加该特性可以正常工作，但想了解需要在OpenAPI规范（如下述YAML代码）中添加什么配置，才能让特定API路径自动生成这个特性？

/Thing:
  get:
    summary: Returns a list of Things.
    responses:
      "200": # status code
        description: A JSON array of Things
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Thing"

解决方案 #

有两种配置方式可以实现自动生成[Authorize(Roles = "User")]特性，按需选择即可：

方式一：遵循OpenAPI标准Security配置

这种方式符合OpenAPI规范，同时能被NSwag识别：

1. 先在OpenAPI的components节点下定义认证方案（以JWT为例）：

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

2. 在目标接口的get操作里添加security字段，指定需要的角色：

/Thing:
  get:
    summary: Returns a list of Things.
    security:
      - BearerAuth: ["User"] # 指定需要User角色
    responses:
      "200":
        description: A JSON array of Things
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Thing"

最后在NSwagStudio的代码生成设置中，找到Controller Settings，勾选"Generate Authorize attributes from security requirements"选项，确保该功能启用。

方式二：使用NSwag自定义扩展属性

如果不想配置标准认证方案，直接给接口添加NSwag专属的扩展字段更简单：
在目标接口的get操作里添加x-nswag-authorize扩展，指定角色：

/Thing:
  get:
    summary: Returns a list of Things.
    x-nswag-authorize:
      roles: "User" # 直接指定需要的角色
    responses:
      "200":
        description: A JSON array of Things
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Thing"

这种方式无需额外配置NSwagStudio开关，只要使用的NSwag版本为v13及以上，就能自动生成对应的Authorize特性。

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