Get currently available versions without running the API

[spaasis]

I'm wondering how to automate the deployment of APIs to Azure API Management.

We can currently generate a swagger.json for a specific version via https://www.nuget.org/packages/Swashbuckle.AspNetCore.Cli
by e.g. dotnet swagger tofile --output ../frontend/swagger.json $(OutputPath)$(AssemblyName).dll v1
This could be used to get fresh OpenApi specs for each version.

But how could I go about getting every currently available version? Since each deployment may add new versions, deprecate or delete old ones or update many versions at once managing the active version separately from code (a pipeline variable for example) seems very brittle.

One possibility, I guess, would be to fire up the site, perform a query and inspect the headers to find the supported versions. Is there any way to extract these from the command line directly?

[commonsensesoftware]

This can definitely be done from a technical standpoint. The IApiVersionDescriptionProvider service will return all known API versions, whether they are deprecated, and any sunset policy information. My understanding of how this works with the Swashbuckle CLI is that it spins up your app using TestHost in-memory and then extrapolates the information. That allows DI and just about everything else to function without hosting the application for real.

The biggest challenge is getting the API Versioning information to be understood by Swashbuckle and vice versa. Neither knows about each other. Furthermore, I don't know that there is an extensibility model for .NET Tools (but that would be cool). If that existed, then an API Versioning extension to the Swashbuckle CLI could make it work. It's certainly possible an API Versioning CLI tool that can output that information, but then I don't know how you'd get it into the Swashbuckle CLI.

The bridge between Swashbuckle and API Versioning is the API Explorer. In Swashbuckle parlance, it uses a document name to match up to an endpoint name. Both of these names are typically defined by ApiVersionDescription.GroupName when you combine the two. This name must also match up to ApiDescription.GroupName to be included in the document.

If Swashbuckle were to provide a list of that information (e.g. distinct names) that would probably achieve your goal. Unfortunately, you won't know about entire API versions that are deprecated because it's not understood by Swashbuckle. Swashbuckle definitely would know that an API is deprecated when creating a document. It could follow the same logic and indicate that a group is deprecated if every API in it is marked with Deprecated = true.

There might be some other methods, but that's my initial thoughts. Given that the logic would almost certain have to be inside the Swashbuckle CLI, it would likely have to be a change on that side. Rich might be receptive to the enhancement, but I can't say for sure.

[spaasis]

Thanks for the detailed response. Encouraged by it, I took a look inside the CLI code and it would seem pretty straightforward to modify for this purpose. A couple new parameters and looping through all groupNames should do the trick. I'll see how far that gets me