如何在ASP.NET Core 8 Web API项目中配置Swagger示例值

当然可以在ASP.NET Core 8 Web API项目里配置Swagger的「示例值」，下面给你两种适配你现有XML注释的实现方案：

你提供的意大利语XML注释翻译版 #

<member name="M:BD.User.DWA.Services.BDUserController.GetDynamicTokenExt(Newtonsoft.Json.Linq.JObject)">
     <summary>
     该方法根据userKey、appId、fingerPrint和data参数，返回加密令牌、明文启用模块以及记账响应结果。
     </summary>
     <param name="oInputParams">包含输入参数的JSON对象</param>     
     <remarks>
     请求示例：
     
         POST /api/BD.User.BDUserServiceREST.svc/GetDynamicTokenExt
         {
             "parameters":{
                 "userKey": "as_smart01",
                 "appId": "4241",
                 "isSIACUser": false,
                 "data": {
                     "environment": "ON",
                     "modules": [
                         "1"
                     ],
                     "accountType": 0
                 }
             }
         }
         
     </remarks>
     <returns></returns>
 </member>

方案一：基于现有<remarks>注释提取示例 #

默认Swagger不会自动把<remarks>里的JSON当成请求示例，需要写个自定义过滤器实现：

1. 启用XML文档生成
   右键项目 → 属性 → 生成 → 勾选「XML文档文件」，设置输出路径（比如$(SolutionDir)\XmlDocs\$(AssemblyName).xml），还可以把1591添加到「禁止显示警告」里，避免因缺少注释报错。

2. 配置Swagger加载XML注释
   在Program.cs里添加Swagger服务配置：

builder.Services.AddSwaggerGen(c =>
{
    // 加载当前项目的XML注释文件
    var xmlFile = $"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

3. 编写自定义操作过滤器
   创建过滤器类，提取<remarks>里的JSON示例并设置到Swagger中：

public class RemarksExampleFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 从API描述中获取remarks内容
        var remarks = context.ApiDescription.ActionDescriptor.EndpointMetadata
            .OfType<Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription>()
            .FirstOrDefault()?.Documentation;

        if (string.IsNullOrEmpty(remarks)) return;

        // 提取remarks中的JSON部分
        var jsonLines = remarks.Split(new[] { '\n', '\r' }, StringSplitOptions.RemoveEmptyEntries)
            .SkipWhile(line => !line.TrimStart().StartsWith("{"))
            .TakeWhile(line => !line.TrimEnd().EndsWith("}") || line.TrimEnd() == "}")
            .ToList();

        if (!jsonLines.Any()) return;

        var exampleJson = string.Join("\n", jsonLines);
        // 设置请求示例
        operation.RequestBody?.Content.TryGetValue("application/json", out var content);
        content?.Examples.Add("自定义示例", new OpenApiExample
        {
            Value = OpenApiAnyFactory.CreateFromJson(exampleJson),
            Summary = "请求示例"
        });
    }
}

4. 注册过滤器
   在Swagger配置里添加过滤器注册：

builder.Services.AddSwaggerGen(c =>
{
    // ... 之前的XML注释加载代码 ...
    c.OperationFilter<RemarksExampleFilter>();
});

方案二：改用<example>标签（更简单） #

如果能修改XML注释，直接用<example>标签定义请求示例，Swashbuckle会自动识别并显示，不用写过滤器：

<param name="oInputParams">包含输入参数的JSON对象</param>
<example>
{
    "parameters":{
        "userKey": "as_smart01",
        "appId": "4241",
        "isSIACUser": false,
        "data": {
            "environment": "ON",
            "modules": [
                "1"
            ],
            "accountType": 0
        }
    }
}
</example>

配置完成后，Swagger控制台的请求区域就会显示你定义的示例值，替代默认的自动生成内容。

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