V4 Azure Function集成Swagger UI空白且报HTTP 500错误排查

问题现象 #

在V4 Azure Function中配置Swagger后，本地运行时日志能正常显示Swagger端点（如localhost:8190/api/swagger/ui），但访问该端点时返回HTTP 500错误，页面显示空白。

最初配置代码 #

program.cs #

using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker.Extensions.OpenApi.Extensions;

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

host.Run();

函数实现代码 #

using System.Net;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;

namespace MyFunctionApp
{
    public static class MyFunction
    {
        [Function("MyFunction")]
        [OpenApiOperation(operationId: "Run", tags: new[] { "name" })]
        [OpenApiParameter(name: "name", In = ParameterLocation.Query, Required = true, Type = typeof(string), Description = "The **Name** parameter")]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string), Description = "The OK response")]
        public static HttpResponseData Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req)
        {
            var query = System.Web.HttpUtility.ParseQueryString(req.Url.Query);
            string name = query["name"];

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "application/json");

            var responseBody = JsonConvert.SerializeObject(new { message = $"Hello, {name}!" });
            response.WriteString(responseBody);

            return response;
        }
    }
}

问题排查与解决 #

通过新建仅保留必要配置的函数应用对比测试，发现原项目的program.cs中额外添加了.ConfigureWebHostDefaults()语句，移除该语句后，Swagger UI即可正常显示。

结论：.ConfigureWebHostDefaults()与V4 Azure Function的OpenAPI配置存在冲突，会干扰Swagger端点的正常加载流程，导致HTTP 500错误。

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