如何为C# Azure Function的Swagger UI GET参数添加定义与示例？

要给C# Azure Function的Swagger文档补充参数定义、示例，推荐使用Microsoft.Azure.WebJobs.Extensions.OpenApi扩展包，这是Azure官方支持的OpenAPI/Swagger生成工具，以下是具体实现步骤：

1. 安装必要NuGet包 #

通过.NET CLI或NuGet包管理器安装：

dotnet add package Microsoft.Azure.WebJobs.Extensions.OpenApi

2. 启用XML文档生成 #

右键项目 → 属性 → 生成 → 勾选「XML文档文件」，指定生成路径（例如bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml）。Swagger会读取这些XML注释生成参数说明。

3. 修改Function代码，添加参数元数据 #

在Function方法和参数上添加XML注释，同时使用[OpenApiParameter]等属性配置Swagger专属的示例、描述信息：

using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.OpenApi.Models;
using System.Net;

/// <summary>
/// 获取队列及现场客户信息
/// </summary>
/// <param name="req">HTTP请求消息</param>
/// <param name="client">CosmosDB文档客户端</param>
/// <param name="companyId">公司唯一ID</param>
/// <param name="branchId">分支门店ID</param>
/// <param name="waitingFields">等待队列需返回的字段（逗号分隔）</param>
/// <param name="calledFields">已叫号客户需返回的字段（逗号分隔）</param>
/// <param name="log">日志记录器</param>
/// <returns>客户队列数据响应</returns>
[OpenApiOperation(operationId: "GetCustomersInQueuesAndField", 
                  tags: new[] { "客户队列" }, 
                  Summary = "查询队列与现场客户信息", 
                  Description = "按公司、分支筛选，指定返回字段，从CosmosDB获取客户队列数据")]
[OpenApiParameter(name: "companyId", 
                  In = ParameterLocation.Path, 
                  Required = true, 
                  Type = typeof(string), 
                  Summary = "公司唯一标识", 
                  Description = "用于区分不同企业的业务数据", 
                  ExampleValue = "COMP001")]
[OpenApiParameter(name: "branchId", 
                  In = ParameterLocation.Path, 
                  Required = true, 
                  Type = typeof(string), 
                  Summary = "分支门店标识", 
                  Description = "区分同一公司下的不同门店/网点", 
                  ExampleValue = "BRANCH001")]
[OpenApiParameter(name: "waitingFields", 
                  In = ParameterLocation.Path, 
                  Required = true, 
                  Type = typeof(string), 
                  Summary = "等待队列返回字段", 
                  Description = "多个字段用英文逗号分隔，指定需查询的等待队列相关字段", 
                  ExampleValue = "CustomerName,QueueNumber,WaitTime")]
[OpenApiParameter(name: "calledFields", 
                  In = ParameterLocation.Path, 
                  Required = true, 
                  Type = typeof(string), 
                  Summary = "已叫号返回字段", 
                  Description = "多个字段用英文逗号分隔，指定需查询的已叫号客户相关字段", 
                  ExampleValue = "ServiceType,CounterNumber,CalledTime")]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, 
                         contentType: "application/json", 
                         bodyType: typeof(IEnumerable<CustomerInfo>), 
                         Summary = "查询成功", 
                         Description = "返回符合条件的客户队列详情")]
public async Task<HttpResponseMessage> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "GetCustomersInQueuesAndField/{companyId}/{branchId}/waitingfields/{waitingFields}/calledfields/{calledFields}")] HttpRequestMessage req,
    [CosmosDB(databaseName: "COSMOS:DATABASE",
       collectionName: "COSMOS:LATCH_TRIGGER_ITEMS_CONTAINER",
       ConnectionStringSetting: "COSMOS:CONNECTION_STRING"
    )] DocumentClient client,
    string companyId,
    string branchId,
    string waitingFields,
    string calledFields,
    ILogger log)
{
    // 原有业务逻辑代码
    return req.CreateResponse(HttpStatusCode.OK, /* 返回数据 */);
}

/// <summary>
/// 客户队列信息模型
/// </summary>
public class CustomerInfo
{
    /// <summary>
    /// 客户姓名
    /// </summary>
    [OpenApiProperty(Summary = "客户姓名", Description = "等待/已叫号客户的姓名", Example = "张三")]
    public string CustomerName { get; set; }

    /// <summary>
    /// 队列编号
    /// </summary>
    [OpenApiProperty(Summary = "队列编号", Description = "客户在等待队列中的序号", Example = "Q005")]
    public string QueueNumber { get; set; }

    // 按需添加其他属性及注释
}

4. 配置OpenApi（根据Function宿主模型） #

进程内模型（In-Process） #

添加Startup.cs类配置OpenApi：

using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;

[assembly: FunctionsStartup(typeof(YourNamespace.Startup))]
namespace YourNamespace
{
    public class Startup : FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
            builder.AddOpenApi();
        }
    }
}

隔离进程模型（Isolated Worker） #

在Program.cs中启用OpenApi：

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureOpenApi()
    .Build();

host.Run();

5. 查看效果 #

运行Function后，访问地址：https://<你的Function域名>/api/swagger/ui，即可看到带参数说明、示例的Swagger界面，与你期望的效果一致。

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