Allow C# Microsoft.Extensions.ApiDescription.Server package to generate 3.0.x OpenAPI specifications on Build

Hi @Eric Fitskie ,

For build-time generation with Microsoft.Extensions.ApiDescription.Server, the OpenAPI version should be set through the MSBuild option OpenApiGenerateDocumentsOptions, not only through AddOpenApi() in code.

For example, in the .csproj file:

<PropertyGroup>
  <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
  <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
  <OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_0</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

I tested this with an ASP.NET Core Web API project using Microsoft.Extensions.ApiDescription.Server 10.0.9. With --openapi-version OpenApi3_0, the build-time generated document started with "3.0.4"

When changing it to OpenApi3_1, it generated the 3.1 document as expected.

So for your case, please try adding --openapi-version OpenApi3_0 to OpenApiGenerateDocumentsOptions. The ASP.NET Core OpenAPI documentation also mentions that build-time generation can select the OpenAPI version through this MSBuild option: Generate OpenAPI documents

One thing to note, Azure API Management has limitations around OpenAPI 3.1 support, so generating a 3.0.x document is the safer path for APIM import: API import restrictions and known issues

If you found my response helpful or informative, I would greatly appreciate it if you could follow this guidance or provide feedback.

Thank you.