Using AddVersionedApiExplorer() with AddMvc()

It seems the AddVersionedApiExplorer() call is always used together with AddMvcCore(). It does not seem to be available with the standard AddMvc() builder. Is this correct? Do I have to convert my application to use the AddMvcCore() builder instead if I want the versioned version?

[commonsensesoftware]

Typically, the only options you’re ever interested in for the API Explorer is:

• GroupNameFormat
• SubstitutionFormat (URL segment style only)
• SubstituteApiVersionInUrl (URL segment style only)
• DefaultApiVersionParameterDescription

GroupNameFormat is generally the only thing you need to change from the out-of-the-box experience. If you’re using the URL segment style, then most prefer SubstituteApiVersionInUrl = true as well. Everything else is choice, but is usually fine as is.

I see the confusion. The API Explorer model in ASP.NET Core is quite different (and more robust) than it was in Web API. The default API Explorer actual discovers everything, but there is no organization to it. The API Versioning provider runs at the end of the API Explorer pipeline and collates all the APIs into appropriate buckets by API version. Technically, AddVersionedApiExplorer() doesn’t depend on AddApiExplorer(), but it also doesn’t make sense without it so it probably should call AddApiExplorer() on your behalf. I’ll consider adding that to the 3.0 work in progress.

Your suggestion is valid, but - unfortunately - I find a lot of people mixing and matching API versioning with UIs. I don’t know why anyone needs API versioning if you own both the UI and API in the same application, but I see it quite often. For that reason, the current example should probably stay as is. It’s useful for those mixing in with the full MVC stack and I use the samples quite often as the basis of for troubleshooting.

That said, I’m not at all opposed to an entirely new sample. Perhaps something called ApiOnlySample that has the setup you are describing. The controllers will need to change their base type to ControllerBase instead of Controller as well. There may be other changes required too, but that’s what I can think of off the top of my head.

[commonsensesoftware]

No problem. You can, and will ultimately need, to call both. AddMvc() calls AddMvcCore() internally. There’s nothing wrong with calling them both, even multiple times.

Since you’re using the full MVC stack, you should expect your setup to update to:

public void ConfigureServices( IServiceCollection services )
{
    // the api explorer doesn't require the UI and you might not be using it,
    // which is why it's on AddMvcCore
    services.AddMvcCore().AddVersionedApiExplorer();
    services.AddMvc();
    services.AddApiVersioning();

The Swagger Sample shows a more complete example. I hope that helps and clears things up. Don’t hesitate to keep asking questions.