如何将.NET Azure Functions的OpenAPI版本切换为3.x？

前提条件 #

确保你的项目安装了Microsoft.Azure.WebJobs.Extensions.OpenApi NuGet包（版本v1.5.0及以上，该版本开始原生支持OpenAPI 3.0），如果版本过低，先更新包。

修改步骤 #

1. 添加或更新Startup配置类
   如果项目中没有Startup.cs，新建一个继承FunctionsStartup的类；如果已有，直接修改现有配置：

   using Microsoft.Azure.Functions.Extensions.DependencyInjection;
   using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Configurations;
   using Microsoft.Extensions.DependencyInjection;
   
   [assembly: FunctionsStartup(typeof(YourProjectNamespace.Startup))]
   namespace YourProjectNamespace
   {
       public class Startup : FunctionsStartup
       {
           public override void Configure(IFunctionsHostBuilder builder)
           {
               // 配置OpenAPI选项，指定版本为3.0
               builder.Services.Configure<OpenApiOptions>(options =>
               {
                   options.OpenApiVersion = OpenApiVersionType.V3;
                   options.Title = "你的API名称";
                   options.Version = "v1";
               });
           }
       }
   }
   

   替换YourProjectNamespace为你项目的实际命名空间，按需调整API标题和版本号。

2. 重启项目验证
   重新启动Azure Functions项目，访问http://localhost:{你的端口}/api/swagger.json，此时返回的JSON中会显示openapi: "3.0.x"（替代原有的swagger: "2.0"），说明版本切换成功。

注意事项 #

如果你的项目之前使用的是Microsoft.Azure.WebJobs.Extensions.Swashbuckle包，建议切换到Microsoft.Azure.WebJobs.Extensions.OpenApi，因为前者仅支持Swagger 2.0，后者是官方针对OpenAPI 3.0的集成方案。

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