Microsoft.Extensions.ApiDescription.Server does not respect OpenAPI version set in code
- 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
Assessment
This issue has not been assessed yet.