如何在ASP.NET Core 6 Web API中为自动生成的openapi.json添加示例值？

当然可以，ASP.NET Core 6 Web API结合Swashbuckle.AspNetCore（默认用来生成OpenAPI文档的工具），有多种方式可以给API动作添加示例值，这些示例会自动同步到生成的openapi.json文件，并在Swagger UI中展示。

ASP.NET Core支持读取XML注释生成OpenAPI元数据，你可以在模型属性或API参数上添加<example>标签来指定示例。

操作步骤：

• 右键项目 → 属性 → 生成 → 勾选“XML文档文件”，设置生成路径（比如$(SolutionDir)\XmlDocs.xml）。
• 在Program.cs中配置Swagger时，添加读取XML注释的代码：

builder.Services.AddSwaggerGen(c =>
{
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

• 在模型或API参数上添加示例：

public class UserRequest
{
    /// <summary>
    /// 用户姓名
    /// </summary>
    /// <example>张三</example>
    public string Name { get; set; }

    /// <summary>
    /// 用户年龄
    /// </summary>
    /// <example>25</example>
    public int Age { get; set; }
}

[HttpPost]
public IActionResult CreateUser([FromBody] UserRequest request)
{
    // 业务逻辑代码
    return Ok();
}

先安装Swashbuckle.AspNetCore.Annotations NuGet包，之后可以用专属特性快速指定示例。

2.1 给模型属性加单个示例 #

using Swashbuckle.AspNetCore.Annotations;

public class UserRequest
{
    [SwaggerSchema(Example = "张三")]
    public string Name { get; set; }

    [SwaggerSchema(Example = 25)]
    public int Age { get; set; }
}

2.2 给请求/响应加完整示例 #

如果需要给整个请求体或响应体添加复杂结构的示例，可以实现IExamplesProvider接口，再通过特性绑定到API动作上：

using Swashbuckle.AspNetCore.Filters;

// 定义请求示例提供器
public class UserRequestExample : IExamplesProvider<UserRequest>
{
    public UserRequest GetExamples()
    {
        return new UserRequest
        {
            Name = "李四",
            Age = 30
        };
    }
}

// 绑定到API动作
[HttpPost]
[SwaggerRequestExample(typeof(UserRequest), typeof(UserRequestExample))]
[SwaggerResponseExample(200, typeof(UserResponseExample))] // 同理可定义响应示例
public IActionResult CreateUser([FromBody] UserRequest request)
{
    return Ok(new UserResponse { Id = 1, Name = request.Name });
}

// 在Program.cs中启用示例过滤器
builder.Services.AddSwaggerExamplesFromAssemblyOf<UserRequestExample>();
builder.Services.AddSwaggerGen(c =>
{
    // 其他Swagger配置...
    c.ExampleFilters();
});

如果需要全局统一处理某些类型的示例，或者给特定API批量添加示例，可以自定义ISchemaFilter：

public class CustomSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // 针对UserRequest类型添加示例
        if (context.Type == typeof(UserRequest))
        {
            schema.Example = new OpenApiObject
            {
                ["Name"] = new OpenApiString("王五"),
                ["Age"] = new OpenApiInteger(28)
            };
        }
        // 可扩展其他类型的全局示例逻辑
    }
}

// 在Program.cs中注册过滤器
builder.Services.AddSwaggerGen(c =>
{
    c.SchemaFilter<CustomSchemaFilter>();
});

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