[Swagger] ApiVersionNeutralAttribute clarification

[westfin]

Hi guys, could you please explain how ApiVersionNeutralAttribute works with swagger generator?

We have ApiVersioning like that:

serviceCollection.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new HeaderApiVersionReader("X-Api-version");
    options.ApiVersionSelector = new ConstantApiVersionSelector(ApiVersion.Default);
}).AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
});

And we have single controller with ApiVersionNeutralAttribute.
With such configuration I don't have any info about X-Api-version header in my resulting document. But If I'm commenting attribute then the header appeared as required header parameter.

My expectation that openapi document with ApiVersionNeutralAttribute should have optional X-Api-Version header parameter. Does my assumption wrong?
Could you please explain the exact behavior? Or point me to any documentation, thanks :)

[commonsensesoftware]

When an API is version-neutral, it will accept any API version, including none at all. In terms of API collation, a version-neutral API will appear in a group for every API version. This posits an interesting question. Should a version-neutral document an API version? It can and it would not be wrong, but it doesn't have to. Most people have indicated that they do not want to see or document the API version as input in these cases, so that is the default behavior. This can be easily be changed however. The magic is setting the AddApiVersionParametersWhenVersionNeutral option to true. For example:

serviceCollection.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new HeaderApiVersionReader("X-Api-version");
    options.ApiVersionSelector = new ConstantApiVersionSelector(ApiVersion.Default);
}).AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.AddApiVersionParametersWhenVersionNeutral = true;
});

With this option enabled, all version-neutral APIs will show the API version parameter(s) just like any other API.

[westfin]

Awesome, thanks @commonsensesoftware!