Swashbuckle.aspnetcore: 30 minutes lost because of misleading intellisense (Unknown Swagger document - v1)

[JCKodel]

When running, I was getting a Unknown document exception, and I couldn't find why =(

Then, I saw another issue (non related) and the OP gave a github link of his project, then I figured out where I did wrong:

Notice the intellisense ask me for NAME, but what it really wants is a VERSION!

Just change the argument name from name to version and correct the description from A URI-friendly name that uniquely identifies the document to A URI-friendly version info (i.e. v1) that uniquely identifies the document.

Link all those parts where versioning is used on documentation:

1) On services.AddSwaggerGen => SwaggerDoc("HERE")
2) On app.UseSwaggerUI => SwaggerEndpoint("/swagger/HERE/swagger.json", "Title")
3) On every controller in attribute [ApiExplorerSettings(GroupName = "HERE")]

[domaindrivendev]

Firstly, learn the appropriate etiquette for contributing feedback to an OSS project. For example, don't moan about losing 30 mins in the title and instead consider the fact that the author has literally put thousands of personal hours into providing you with this extremely helpful tool at no charge.

Secondly, you're incorrect. The "name" parameter is referring to the name of the Swagger document, and NOT the version. One common use case is to name the document based on the version of the API it describes. However, you might also have logically separate services hosted by the same ASP.NET core app and in that case you may choose to create separate Swagger documents for each one. As an example ...

c.SwaggerDoc("Products API", productsApiInfo)
c.SwaggerDoc("Orders API", ordersApiInfo)

So, name CAN correlate to version but doesn't have to. Calling the parameter "version" would be over-specifying. It's a "Swagger document" that contains arbitrarily grouped operation descriptions. Focus on the document abstraction, version is just one use-case.

[PaulDotNet]

Hello author.
Sorry for my etiquette but get more contributors! I have one pull request already and would be happy to help a bit. Maybe even add some comments to improve intellisense. We could saved the world 30 minutes at a time.