Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

[Swagger] ApiVersionNeutralAttribute clarification #998

Discussion options

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 :)

You must be logged in to vote

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;
 opt...

Replies: 1 comment 1 reply

Comment options

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.

You must be logged in to vote
1 reply
Comment options

Awesome, thanks @commonsensesoftware!

Answer selected by westfin
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Category
Q&A
Labels
None yet

AltStyle によって変換されたページ (->オリジナル) /