为 Swagger 文档创建自定义属性或类

Question

我想知道是否有任何方法可以创建一个自定义类或属性，我可以调用它并将所有 swagger 文档属性保留在一个地方，例如这是我的原始代码

 [HttpGet]
 [SwaggerOperation(
        Summary = "Get the list of customers",
        Description = "This Api returns the list of customers from database and and display on Customer Screen",
        Tags = ["Customer"]
    )
]
[SwaggerResponse(200, description: "Returns a list of customers if the request was successful.")]
[SwaggerResponse(500, "Internal Server Error along with the complete Error message.")]
public async Task<ActionResult> GetCustomersAsync(CancellationToken cancellationToken)
{
    // Code to Get the customers
    return Ok(customers);
}

我想知道，有什么方法可以减少所有这些代码并创建一个自定义属性类并传递值，像这样

[AttributeUsage(AttributeTargets.Method, Inherited = true)]
public class SwaggerDocumentation : Attribute
{
    public SwaggerDocumentation(string operationSummary, string operationDescription, List<string> operationTags, string responseSuccessMessage)
    {
      // I am not sure what will come here, but ideally this is how it should look like
      [SwaggerOperation(
        Summary = operationSummary,
        Description = operationDescription,
        Tags = operationTags)]

      [SwaggerResponse(200, description: $"Returns a {responseSuccessMessage} if the request was successful.")]
      [SwaggerResponse(500, "Internal Server Error along with the complete Error message.")]
    }  
}

然后用类似的东西装饰我的函数

 [HttpGet]
 [SwaggerDocumentation("MySummary","MyDescription", "MyTags", "List of Customers")]
 public async Task<ActionResult> GetCustomersAsync(CancellationToken cancellationToken)
 {

 }

我什至不确定这是否可能。

Answer 1

我将答案发布在这里是为了其他人的利益。

[AttributeUsage(AttributeTargets.Method)]
public class SwaggerDocumentationAttribute(string summary, string description, string[] tags, string responseSuccessMessage) : Attribute
{
    public string Summary { get; } = summary;
    public string Description { get; } = description;
    public string[] Tags { get; } = tags;
    public string ResponseSuccessMessage { get; } = responseSuccessMessage;
}

然后我创建了另一个从 IOperationFilter 派生的类，感谢 @Martin Costello 的想法。

public class SwaggerDocumentationOperationFilter : IOperationFilter
{
     public void Apply(OpenApiOperation operation, OperationFilterContext context)
     {
         if (context.MethodInfo.GetCustomAttributes(typeof(SwaggerDocumentationAttribute), false)?.FirstOrDefault() is
             not SwaggerDocumentationAttribute descriptionAttribute) 
          return;
    
       var tags = descriptionAttribute.Tags.Select(tagName => new OpenApiTag { Name = tagName }).ToList();
       operation.Summary = descriptionAttribute.Summary;
       operation.Description = descriptionAttribute.Description;
       operation.Tags = tags;

       // Remove the default 200 response, which was added by default by Swashbuckle
       operation.Responses.Remove("200");
        
       operation.Responses.Add("200", new OpenApiResponse { Description = $"Returns a {descriptionAttribute.ResponseSuccessMessage}, if operation was successful." });
       operation.Responses.Add("500", new OpenApiResponse { Description = "Internal Server Error along with the complete Error message." });
     }
}

在我的 AddSwaggerGen 中，我必须添加此过滤器

   c.OperationFilter<SwaggerDocumentationOperationFilter>();

最后我这样称呼它

[HttpGet]
[SwaggerDocumentation("MySummary","MyDescription",["Customer"],"List of Customers")]
public async Task<ActionResult> GetCustomersAsync(CancellationToken cancellationToken)
{

}