如何通过命令行用microsoft.dotnet-openapi生成Azure Function的OpenAPI YAML？

1. 引入适配Azure Functions的Swagger工具包 #

使用Swashbuckle.AspNetCore.Functions包是当前实现该需求的直接方案，它专门针对Azure Functions做了Swagger/OpenAPI生成适配：

• 安装包：执行命令 dotnet add package Swashbuckle.AspNetCore.Functions
• 在Program.cs中配置Swagger服务：

  var builder = WebApplication.CreateBuilder(args);
  builder.Services.AddAzureFunctions();
  
  // 配置Swagger基础生成规则
  builder.Services.AddSwaggerGen(c =>
  {
      c.SwaggerDoc("v1", new() { Title = "你的函数API名称", Version = "v1" });
      // 可选：加载XML注释文件，生成更详细的接口描述
      var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
      var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
      c.IncludeXmlComments(xmlPath);
  });
  // 启用Azure Functions的Swagger扩展适配
  builder.Services.AddSwaggerGenWithAzureFunctions();
  
  var app = builder.Build();
  app.UseSwagger();
  // 可选：启用SwaggerUI可视化调试页面
  app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "你的函数API名称 v1"));
  app.Run();
  

2. 构建后自动生成OpenAPI YAML #

在流水线的构建步骤中添加以下命令，即可在编译完成后自动导出YAML格式的OpenAPI规范文件：

dotnet swagger tofile --output openapi.yaml --yaml bin/Release/net6.0/你的函数项目.dll v1

• 替换你的函数项目.dll为实际编译生成的DLL文件名
• 若使用Debug环境编译，将Release改为Debug

3. 适配OpenAI自定义属性映射 #

如果项目中使用了OpenAI相关的自定义属性，需添加Swagger过滤器将这些属性同步到OpenAPI规范中：

public class OpenAIOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // 提取方法上的OpenAI属性并映射到OpenAPI的扩展字段
        var openAIAttr = context.MethodInfo.GetCustomAttribute<OpenAIAttribute>();
        if (openAIAttr != null)
        {
            operation.Extensions.Add("x-openai-model", new OpenApiString(openAIAttr.ModelName));
            // 根据实际属性需求添加更多映射规则
        }
    }
}

然后在AddSwaggerGen配置中注册该过滤器：

builder.Services.AddSwaggerGen(c =>
{
    // ... 其他基础配置
    c.OperationFilter<OpenAIOperationFilter>();
});

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