【ASP.NET Core Swagger】3、注释（Swashbuckle.AspNetCore.Annotations）

Swashbuckle.AspNetCore.Annotations包括一组可应用于Controller、Action和Model的自定义属性，以丰富生成的 Swagger

安装Nuget

install-package Swashbuckle.AspNetCore.Annotations

启用注释

builder.Services.AddSwaggerGen(options => {
    options.EnableAnnotations();
});

Action元数据（SwaggerOperationAttribute）

        /// <summary>
        /// 创建订单
        /// </summary>
        /// <param name="input"></param>
        /// <param name="param1">参数1</param>
        /// <returns></returns>
        [HttpPost("createorder")]
        [SwaggerOperation(
    Summary = "创建订单-概要描述",
    Description = "创建订单-详细描述",
    OperationId = "CreateOrder11",
    Tags = new[] { "Purchase", "Order" }
)]
        public ActionResult<Order> CreateOrder(
            [FromBody] CreateOrderInput input)
        {
            return new Order { };
        }

响应元数据（SwaggerResponseAttributes）

ASP.NET Core 提供了ProducesResponseTypeAttribute用于列出操作可以返回的不同响应的方法。如上所述，这些属性可以与 XML 注释结合使用，以在生成的 Swagger 中包含对每个响应的人性化描述。如果您希望使用单个属性完成所有这些操作，并避免使用 XML 注释，则可以使用SwaggerResponseAttributes 代替：

        [HttpPost("createorder")]
        [SwaggerResponse(200, "订单创建成功", typeof(Order))]
        [SwaggerResponse(400, "参数错误")]
        public ActionResult<Order> CreateOrder(
            CreateOrderInput input, )
        {
            return new Order { };
        }

参数元数据（SwaggerParameterAttribute、SwaggerRequestBodyAttribute）

public ActionResult<Order> CreateOrder(
            [FromBody, SwaggerRequestBody("订单数据", Required = true)] CreateOrderInput input, 
            [FromQuery, SwaggerParameter("参数1", Required = true)] int param1)
        {
            return new Order { };
        }

Model元数据（SwaggerSchemaAttribute）

此注释可以应用于类和属性

    /// <summary>
    /// 创建订单input参数
    /// </summary>
    [SwaggerSchema(Required = new[] { "创建订单input参数" })]
    public class CreateOrderInput
    {
        [SwaggerSchema("订单号", ReadOnly = true)]
        public int ID { get; set; }
        [SwaggerSchema("订单金额")]
        public decimal TotalPrice { get; set; }
        [SwaggerSchema("创建时间", Format = "date")]
        public DateTime CreateTime { get; set; }
    }

模式过滤器？（SwaggerSchemaFilterAttribute）

// Product.cs
[SwaggerSchemaFilter(typeof(ProductSchemaFilter))]
public class Product
{
    ...
}

// ProductSchemaFilter.cs
public class ProductSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        schema.Example = new OpenApiObject
        {
            [ "Id" ] = new OpenApiInteger(1),
            [ "Description" ] = new OpenApiString("An awesome product")
        };
    }
}

标签元数据

默认情况下，Swagger 生成器将使用控制器名称标记所有操作。然后使用这个标签来驱动 swagger-ui 中的操作分组。如果您想为每个组提供描述，您可以通过以下方式为每个控制器名称标签添加元数据SwaggerTagAttribute：

    [SwaggerTag("订单接口")]
    public class OrderController : ControllerBase
    {}

忽略控制器、Action

[ApiExplorerSettings(IgnoreApi =true)]