swagger 配置 二

 

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
                        new OpenApiInfo
                        {
                            Title = "Test API V1",
                            Version = "v1",
                            Description = "A sample API for testing Swashbuckle",
                            TermsOfService = new Uri("http://tempuri.org/terms")
                        }
                    );

    c.RequestBodyFilter<AssignRequestBodyVendorExtensions>();

    c.OperationFilter<AssignOperationVendorExtensions>();

    c.SchemaFilter<ExamplesSchemaFilter>();

    c.DescribeAllParametersInCamelCase();

    c.UseOneOfForPolymorphism();
    c.UseAllOfForInheritance();

    c.SelectDiscriminatorNameUsing((baseType) => "TypeName");
    c.SelectDiscriminatorValueUsing((subType) => subType.Name);


    string xmlName = Assembly.GetEntryAssembly().GetName().Name + ".xml";
    string xmlPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, xmlName);
    c.IncludeXmlComments(xmlPath, true);
    //参数 例如 Get 方式 查询 OrderName 在swagger上显示的是orderName
    c.DescribeAllParametersInCamelCase();
    // c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Basic.xml"));

    // 确保接口也能被识别为多态基类
    c.GeneratePolymorphicSchemas(info =>
    {
        if (info.IsInterface && info.Name == nameof(IAnimal))
        {
            return new[] { typeof(Cat), typeof(Lion) };
        }
        return Enumerable.Empty<Type>();
    });


    //
    c.EnableAnnotations();
});

 

开启 swagger 注解

类库  Swashbuckle.AspNetCore.Annotations

EnableAnnotations
注解包含 SwaggerRequestBody  SwaggerResponse SwaggerParameter

        /// <summary>
        /// 
        /// </summary>
        /// <param name="order"></param>
        /// <returns></returns>
        /// <remarks>
        /// ## Heading 1
        /// 
        ///     POST /Order
        ///     {
        ///         "id": "123",
        ///         "orderName": "冰箱"
        ///     }
        /// 
        /// </remarks>
        // [HttpPost(Name ="Product")]
        [HttpPost("Product")]
        public IActionResult Post([FromBody, SwaggerRequestBody(Description = "The Auth request body")] Order custormOrder)
        // public IActionResult Post([FromBody] Order order)
        {
            return Ok();
        }
        [SwaggerResponse(200, "成功响应", typeof(Order))]
        [SwaggerResponse(400, "参数错误")]
        [SwaggerOperation(summary: "获取订单", description: "获取订单")]
        [ProducesResponseType(typeof(Order), (int)HttpStatusCode.OK)]
        [HttpGet("GetOrderName")]
        public IActionResult Get([FromQuery, SwaggerParameter(Description = "订单名称", Required = true)] string OrderName)
        {
            Order order = new Order { Id = 1, OrderName = "冰箱订单" };
            return Ok(order);
        }

  对应设置 

 

 

  对应

 

 

设置 swagger 参数 都是驼峰 形式
c.DescribeAllParametersInCamelCase();

 设置 请求体

    c.RequestBodyFilter<AssignRequestBodyVendorExtensions>();

 

    public class AssignRequestBodyVendorExtensions : IRequestBodyFilter
    {
        public void Apply(OpenApiRequestBody requestBody, RequestBodyFilterContext context)
        {
            requestBody.Extensions.Add("x-purpose", new OpenApiString("test111111111"));
        }
    }

 

对应

 

设置 接口描述信息

 

c.OperationFilter<AssignOperationVendorExtensions>();

    public class AssignOperationVendorExtensions : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            operation.Extensions.Add("x-purpose", new OpenApiString("test"));
        }
    }

对应

 

设置 模板信息

c.SchemaFilter<ExamplesSchemaFilter>();

public class ExamplesSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        schema.Example = GetExampleOrNullFor(context.Type);
    }

    private IOpenApiAny GetExampleOrNullFor(Type type)
    {
        switch (type.Name)
        {
            case "Order":
                return new OpenApiObject
                {
                    ["id"] = new OpenApiInteger(123),
                    ["orderName"] = new OpenApiString("冰箱的订单"),
                };
            default:
                return null;
        }
    }
}

对应 的 控制器 代码 的 参数Order

   

        [HttpPost("Product")]
        public IActionResult Post([FromBody, SwaggerRequestBody(Description = "The Auth request body")] Order custormOrder)
        // public IActionResult Post([FromBody] Order order)
        {
            return Ok();
        }

对应

     

 

设置 多态

c.UseOneOfForPolymorphism();
c.UseAllOfForInheritance();
c.SelectDiscriminatorNameUsing((baseType) => "TypeName");
c.SelectDiscriminatorValueUsing((subType) => subType.Name);

// 确保接口也能被识别为多态基类
c.GeneratePolymorphicSchemas(info =>
{
if (info.IsInterface && info.Name == nameof(IAnimal))
{
return new[] { typeof(Cat), typeof(Lion) };
}
return Enumerable.Empty<Type>();
});

 

[SwaggerSubType(typeof(Lion))]
[SwaggerSubType(typeof(Cat))]
public interface  IAnimal
{
    public int Id { get; }
    public string Name { get; }
}

public class Cat : IAnimal
{
    public Cat(int id, string name)
    {
        Id = id;
        Name = name;
    }
    public int Id { get; private set; }
    public string Name { get; private set; }
}

对应代码

        [HttpGet("GetAnimal")]
        public ActionResult<IAnimal> GetAnimal([FromQuery] string animalType)
        {
            IAnimal animal = new Lion(1, "狮子");
            return Ok(animal);
        }

对应