Azure Function集成Swagger/OpenApi启用请求响应特性报错排查

问题描述 #

集成Azure Function、Swagger与OpenApi时，未启用OpenApiRequestBody或OpenApiResponseWithBody注释前，访问Swagger主页（.../api/swagger/ui）一切正常。但取消这两个注释的任意一个后，页面出现错误：

Fetch error. Internal Server Error http://localhost:7031/api/swagger.json

注：swagger.json文件确实存在于正确路径。

相关代码 #

[Function("v1/job/selectAll/{agentId}")]
[OpenApiOperation(operationId: "selectAllJpbs", tags: new[] { nameof(TctJob) }, Summary = "Select all jobs.", Description = "This select all the jobs of an agent.", Visibility = OpenApiVisibilityType.Important)]
//[OpenApiSecurity("petstore_auth", SecuritySchemeType.OAuth2, Flows = typeof(PetStoreAuth))]
[OpenApiParameter(name: "agentId", In = ParameterLocation.Query, Description = "The id of the agent to download the jobs", Required = true, Type = typeof(Guid))]
//[OpenApiRequestBody(contentType: "application/json", bodyType: typeof(List<TctJob>), Required = true, Description = "List of all the jobs of the requested agent.")]
//[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(System.Collections.Generic.List<ITctJob>), Summary = "Job list.", Description = "List of all the jobs.")]
[OpenApiResponseWithoutBody(statusCode: HttpStatusCode.BadRequest, Summary = "Invalid ID supplied", Description = "Invalid ID supplied")]
[OpenApiResponseWithoutBody(statusCode: HttpStatusCode.NotFound, Summary = "", Description = "")]
[OpenApiResponseWithoutBody(statusCode: HttpStatusCode.MethodNotAllowed, Summary = "Validation exception", Description = "Validation exception")]
public async Task<IActionResult> SelectAllJobs(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequestData req,
    [FromRoute(Name = "agentId")] Guid agentId)
{ ... }

环境信息 #

• 目标框架：.NET 6
• Azure Function版本：v4
• AzureExtensions.Swashbuckle：3.3.2

更新：项目.csproj文件 #

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net6.0</TargetFramework>
        <AzureFunctionsVersion>v4</AzureFunctionsVersion>
        <OutputType>Exe</OutputType>
        <!--<Nullable>enable</Nullable>-->
        <AssemblyVersion>1.0.0</AssemblyVersion>
        <PackageVersion>1.0.0</PackageVersion>
        <Authors>The Cloud Team</Authors>
        <Company>The Cloud Team</Company>
        <Description>This package contains the Database Updater service.</Description>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.16.0" />
        <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Abstractions" Version="1.2.0" />
        <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.0.13" />
        <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.11.0" />
    </ItemGroup>
    <ItemGroup>
      <ProjectReference Include="..\..\..\TCT.Backend.Services.Common\TCT.Backend.Services.Common\TCT.Backend.Services.Common\TCT.Backend.Services.Common.csproj" />
      <ProjectReference Include="..\..\..\TCT.Common\TCT.Common\TCT.Common.csproj" />
    </ItemGroup>
    <ItemGroup>
        <None Update="host.json">
            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
        <None Update="local.settings.json">
            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
            <CopyToPublishDirectory>Never</CopyToPublishDirectory>
        </None>
    </ItemGroup>
</Project>

解决建议 #

• 移除GET请求的OpenApiRequestBody注释：HTTP规范中GET请求不应携带请求体，Swashbuckle生成OpenApi文档时会因这个矛盾抛出异常，直接删除该注释即可。
• 将响应体的接口类型替换为具体实现类：OpenApiResponseWithBody中使用了List<ITctJob>接口类型，Swashbuckle无法为接口生成有效的Schema。将其改为List<TctJob>（具体实体类），确保序列化器能识别并生成正确的文档结构。
• 升级兼容的依赖包版本：将AzureExtensions.Swashbuckle升级到最新稳定版（如3.4.0及以上），同时确保Microsoft.Azure.Functions.Worker系列包版本与Swashbuckle包兼容，避免版本冲突导致的文档生成错误。
• 启用Nullable检查（可选）：取消csproj中<Nullable>enable</Nullable>的注释，提前发现类型定义中的潜在问题，减少序列化相关的异常。
• 验证实体类的可序列化性：确保TctJob类为public访问级别，所有需要序列化的属性均为public，无循环引用。必要时可添加[DataContract]和[DataMember]属性标记需要参与序列化的成员。

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