0

I am using Swashbuckle to embed Swagger documentation for our API into our .NET Web API 2.2 application (.NET 4.5). Up until now all the controllers have lived in the main Web API dll but as we start building out the API we are moving different version APIs to separate dlls.

When specifying a custom asset in Swashbuckle it is possible to specify 1 assembly for a resource path e.g. "v1" -> V1Assembly. However, I want to support the ability for the user to be able to view all API endpoints across all versions and assemblies. How do I make sure that this functionality is feasible with Swashbuckle? Essentially, I want a "all" or "index" endpoint on the help system to show all potential API Resources across all versioned assemblies.

My thought was a new feature that extends the SwaggerUiConfig to allow CustomAsset to accept an array of assemblies instead of just one so that we could interrogate multiple assemblies to generated the documentation instead of just the single one.

Any thoughts on how to accomplish this in the SwaggerConfig or otherwise?

abraganza
  • 135
  • 2
  • 9
  • Random thought: Swashbuckle is based on the generated XML documentation file you generate. So if you generated a combined file and pointed Swashbuckle to it, your problem should be solved. – Quality Catalyst Feb 14 '18 at 18:36
  • Thanks for the suggestion. That is an interesting point and definitely merits some research. Only problem would be figuring out how to merge xml from multiple assemblies into one assembly. I wonder if I were to specify the same xml name for all the assemblies, if it would make one giant aggregated assembly. That helps with the documentation, but how does one reconcile that with the live API calls? – abraganza Feb 14 '18 at 19:37

1 Answers1

2

If I understand correctly when you started versioning you ended up with multiple Web API.

You should consider refactoring your code using aspnet-api-versioning
All you will need to do in the controllers is identify them using something like:
[ApiVersion( "AreaOne" )]
https://github.com/Microsoft/aspnet-api-versioning/wiki/How-to-Version-Your-Service
For that Swashbuckle has full support.

Helder Sepulveda
  • 15,500
  • 4
  • 29
  • 56
  • I tried to find the mentioned attribute but couldn't find it. Is it in a later version of .NET than we are currently on (we are currently on .NET 4.5)?. The plan is to migrate to the latest version and utilize ASP.NET Core but this step needs to be completed before that change occurs. – abraganza Feb 14 '18 at 19:54
  • 1
    @abraganza Do you have aspnet-api-versioning in your references? if not add it from nuget – Helder Sepulveda Feb 14 '18 at 19:57
  • Got it thanks. Will try it out and see if it helps with Swashbuckle... had to install Microsoft.AspNet.WebApi.Versioning – abraganza Feb 14 '18 at 20:51