ApiVersioning and DefaultApiVersion / AssumeDefaultVersionWhenUnspecified weird side effects

[hidegh]

I was adding API versioning to my project, listing concrete versions was fine. Issue is when I do define a default route without any version segment.

Question is how to set up the NSwag so that it:

1. includes the route without versioning segment just in the v1 document (not both in v1 and v2)
2. when there's a default route both without versioning and with the default version

For sample see this project & commit: hidegh/Meal-tracker@a228f04

Just on the MealsController I did define v1/v2/default routing.

NSwag screenshots:

[RicoSuter]

Maybe try

GroupNames = new ["", "v1"]

[RicoSuter]

Or what could be the API Explorer group name for non-versioned operations?

[hidegh]

@RicoSuter

The GroupNames = [""] will return NO result (was trying it). I do have an auto group definition add, but yes, it can be patched... the apiVersionDescriptionProvider.ApiVersionDescriptions do return V1 and V2 only...

I'm experimenting, especially focusing on flexibility as versioning is required with old apps and upgrades, so the existing architecture, solution, URI's are given, the setup is the one should allow the necessary flexibility.

Now it seems that the default (non versioned route) and versioned route works a bit odd, like. I was able to avoid getting the non versioned route to both versions (a logical way that was given, not sure if that flexibility in the long run will be OK for a real project). What is weird is to have the non versioned routes inside the V1 definition which actually doubles each endpoint. It would be interesting to have the "actual" non versioned routes separatelyt from v1/v2 as well...

Issue (not necessarily a bug):

1. the apiVersionDescriptionProvider.ApiVersionDescriptions do return V1 and V2 only
2. if there's multiple route for a single endpoint (one non versioned, other versioned), then we get both displayed in the swagger (is there a way to separate those)?

Last commit with v1/v2 separation: hidegh/Meal-tracker@04314e5 (as I told, it's an experiment, so I DUPED the MealController to have a separate V2)...

[RicoSuter]

In the end you need to figure out how to configure the ASP.NET Core API Explorer so that it reports the correct operations. NSwag only picks up the specified GroupNames and generates them... it's not something which can be "fixed" or changed in NSwag.

[hidegh]

Thank you. If you don't mind, plz. keep this open, when I will have news, will post it there (meanwhile others can also use my repo to experiment with). Btw. quickest "support" here, you even beat the author of Mime/MailKit.NET who released a quick fix whithin 24h while on vacation :D I really like NSwag, although some configs (documentation) are for the old versions (so getting started is not the easiest)... Ev. label this as "not-bug", something that relates to ApiExplorer and documentation.

[RicoSuter]

keep this open, when I will have news, will post it there

Sure.

although some configs (documentation) are for the old versions (so getting started is not the easiest)...

Yeah i know the public config/API surface is huge - mainly because I didnt deprecate old stuff yet (e.g. Web API support).

Related PR which might contain more info:
#1701

Also please update the wiki if something is missing.

And maybe @commonsensesoftware can help here?