dotnet / dotnet/aspnetcore

Microsoft.Extensions.ApiDescription.Server does not respect OpenAPI version set in code

Open
#65,801 5 comments 0 reactions 0 assignees View on GitHub
area-commandlinetools bug feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 10h
Merged PRs (30d)
281

Description

The document file generation does not respect the version set with [`AddOpenApi`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi).

This:

```csharp
builder.Services.AddOpenApi(options =>
{
options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}
```

will show this in `openapi/v1.json`:

```json
{
"openapi": "3.0.4",
"info": {
"title": "MyCompany.MyProduct.AspNetCore.OpenApi | v1",
"version": "1.0.0"
},
```

but this in the generated file:

```json
{
"openapi": "3.1.1",
"info": {
"title": "MyCompany.MyProduct.AspNetCore.OpenApi | v1",
"version": "1.0.0"
},
```

[Docs](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi) say:

> The default OpenAPI version for generated documents is 3.1. The version can be changed by explicitly setting the [OpenApiVersion](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.openapi.openapioptions.openapiversion) property of the [OpenApiOptions](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.openapi.openapioptions) in the configureOptions delegate parameter of [AddOpenApi](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.openapiservicecollectionextensions.addopenapi):
>
> C#
> builder.Services.AddOpenApi(options =>
> {
> // Specify the OpenAPI version to use
> options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
> });
>
> When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the --openapi-version in the OpenApiGenerateDocumentsOptions MSBuild item.
>
> XML
> <!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.1 document -->
> <OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_1</OpenApiGenerateDocumentsOptions>

But there's no mention that generating the OpenAPI document ignores the version that was set in code.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.