Swashbuckle.AspNetCore 注解配置与自定义详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00960/article/details/148505553

Swashbuckle.AspNetCore 注解配置与自定义详解

Swashbuckle.AspNetCore Swashbuckle.AspNetCore：这是一个用于ASP.NET Core的Swagger文档生成器，适合为RESTful API生成API文档。特点包括自动生成API文档、支持多种输出格式（如Markdown、HTML等）、与ASP.NET Core集成良好等。项目地址: https://gitcode.com/gh_mirrors/sw/Swashbuckle.AspNetCore

前言

在 ASP.NET Core Web API 开发中，Swashbuckle.AspNetCore 是一个广泛使用的工具，它可以自动生成 Swagger/OpenAPI 文档。而其中的 Annotations 功能则为我们提供了通过属性注解来丰富 API 文档的能力。本文将深入讲解如何配置和使用这些注解功能。

安装与基础配置

要使用注解功能，首先需要安装对应的 NuGet 包：

dotnet add package Swashbuckle.AspNetCore.Annotations

安装完成后，在 Startup.cs 文件中启用注解功能：

services.AddSwaggerGen(options =>
{
    options.EnableAnnotations();
});

操作元数据增强

SwaggerOperation 注解

[SwaggerOperation] 注解可以丰富 API 操作的元数据：

[HttpPost]
[SwaggerOperation(
    Summary = "创建新产品",
    Description = "需要管理员权限",
    OperationId = "CreateProduct",
    Tags = new[] { "采购", "产品" }
)]
public IActionResult Create([FromBody] Product product)
{
    // 实现代码...
}

参数说明：

Summary：操作的简短描述
Description：详细的操作说明
OperationId：操作的唯一标识符
Tags：用于分组操作的标签数组

响应元数据增强

SwaggerResponse 注解

传统的 ProducesResponseTypeAttribute 需要配合 XML 注释来提供响应描述，而 [SwaggerResponse] 注解可以一站式完成：

[HttpPost]
[SwaggerResponse(201, "产品创建成功", typeof(Product))]
[SwaggerResponse(400, "产品数据无效")]
public IActionResult Create([FromBody] Product product)
{
    // 实现代码...
}

参数元数据增强

SwaggerParameter 注解

对于路径、查询或头部的参数，可以使用 [SwaggerParameter] 注解：

[HttpGet]
public IActionResult GetProducts(
    [FromQuery, SwaggerParameter("搜索关键词", Required = true)] string keywords)
{
    // 实现代码...
}

请求体元数据增强

SwaggerRequestBody 注解

对于请求体参数，可以使用 [SwaggerRequestBody] 注解：

[HttpPost]
public IActionResult CreateProduct(
    [FromBody, SwaggerRequestBody("产品数据负载", Required = true)] Product product)
{
    // 实现代码...
}

模型元数据增强

SwaggerSchema 注解

可以在类或属性上使用 [SwaggerSchema] 注解来增强模型定义：

[SwaggerSchema(Required = new[] { "Description" })]
public class Product
{
    [SwaggerSchema("产品ID", ReadOnly = true)]
    public int Id { get; set; }

    [SwaggerSchema("产品描述")]
    public string Description { get; set; }

    [SwaggerSchema("创建日期", Format = "date")]
    public DateTime DateCreated { get; set; }
}

重要说明：

在 Swagger/OpenAPI 中，序列化对象及其属性都表示为 Schema 实例
必填属性是在顶层 Schema 上通过属性名数组指定的

特定类型的 Schema 过滤器

可以通过 [SwaggerSchemaFilter] 为特定类型应用自定义过滤器：

[SwaggerSchemaFilter(typeof(ProductSchemaFilter))]
public class Product
{
    // 类定义...
}

过滤器实现示例：

public class ProductSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        schema.Example = new OpenApiObject
        {
            ["Id"] = new OpenApiInteger(1),
            ["Description"] = new OpenApiString("一款很棒的产品")
        };
    }
}

标签元数据增强

SwaggerTag 注解

默认情况下，Swagger 会使用控制器名称作为操作标签。可以通过 [SwaggerTag] 为这些标签添加描述：

[SwaggerTag("产品的创建、读取、更新和删除操作")]
public class ProductsController
{
    // 控制器实现...
}

继承和多态支持

显式子类型声明

使用 [JsonDerivedType] 可以显式声明已知的子类型：

[JsonDerivedType(typeof(Rectangle))]
[JsonDerivedType(typeof(Circle))]
public abstract class Shape
{
    // 基类定义...
}

需要在 Startup 中启用相关功能：

services.AddSwaggerGen(options =>
{
    options.EnableAnnotations(
        enableAnnotationsForInheritance: true, 
        enableAnnotationsForPolymorphism: true
    );
});

多态鉴别器元数据

结合 [JsonPolymorphic] 和 [JsonDerivedType] 可以提供更丰富的多态元数据：

[JsonPolymorphic(TypeDiscriminatorPropertyName = "shapeType")]
[JsonDerivedType(typeof(Rectangle), "rectangle")]
[JsonDerivedType(typeof(Circle), "circle")]
public abstract class Shape
{
    // 避免使用与类型层次结构中属性冲突的鉴别器名称
}

对应的枚举定义：

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum ShapeType
{
    Circle,
    Rectangle
}

这将生成包含鉴别器信息的 Schema 定义，清晰地描述了多态类型之间的关系。

总结

Swashbuckle.AspNetCore 的注解功能为 API 文档的丰富和定制提供了强大的支持。通过本文介绍的各种注解，开发者可以：

为操作、参数、响应等添加详细的描述信息
增强模型定义，包括必填字段、格式说明等
实现特定类型的自定义展示
支持复杂的继承和多态场景
提供更清晰的 API 分组和描述

这些功能使得生成的 API 文档更加完整、准确，大大提升了 API 的可理解性和易用性。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考