CODEWITHSUNDEEP
asp.net-web-apiswashbuckle
David Keaveny
David Keaveny

Reputation: 4079

Swashbuckle, multiple API versions, and virtual directories

I am looking at using Swashbuckle/Swagger to document my WebAPI solution. The developer portal would be something like https://myapi.com/, while the versioned API is https://myapi.com/v1/users.

The version part of the URL maps to a virtual directory, containing the binaries and config files for v1. When version 2 ships, we create a new virtual directory under the root, so now we have https://myapi.com/v2/users/some_new_endpoint_not_in_v1. This means that save for bugfixes, there is no need for any of the binaries of older versions to be touched, which reduces the likelihood of some developer accidentally breaking backwards compatibility for our customers.

However, I can't see how to configure Swashbuckle to look at those virtual directories to get the controllers/actions and XML comments to parse. The MultipleApiVersions configuration option seems more targetted at people who throw all their supported versions into one set of binaries (either by namespaces or controller names), and not by separating them into separate processes.

Any suggestions as to how I can bend Swashbuckle to my will? Should I just install Swashbuckle into the individual virtual directories as single API versions, so the docs becomes something like https://myapi.com/v1/swagger? My portal would then do the necessary work to expose the different API versions.

Update

I did try the latter approach, and for the documentation at least, it works OK. The problem is then that the URL for the Swagger spec then becomes https://myapi.com/v1/swagger/docs/v1, and I would rather not have that second v1 in the URL. Unfortunately Swaashbuckle at least expects the version number to be in the relative path, not in the base URL.

Upvotes: 2

Views: 3744

Answers (1)

Benjamin Soulier
Benjamin Soulier

Reputation: 2263

Having those would work:

  • Swagger UI at the root of your API site (nothing to do with Swashbuckle),
  • multiple virtual directories for your versions ("v1", "v2"...)

To achieve this:

  • the custom discoveryPaths array in Swagger UI javascript would look like below, with added "/spec" suffix (or whatever suits you, as SwashBuckle is not handling the c.SingleApiVersion with an empty version value):
var currentUrl = 'https://myapi.com/';
window.swashbuckleConfig = {
    rootUrl: currentUrl,
    discoveryPaths: arrayFrom('v1/swagger/docs/spec|v2/swagger/docs/spec'),
    booleanValues: arrayFrom('true|false'),
    validatorUrl: stringOrNullFrom('null'),
    // other settings ommitted for brevity.
    oAuth2AdditionalQueryStringParams: JSON.parse('{}')
};
  • Removing c.EnableSwaggerUi from your Web API sub apps

Upvotes: 2

Related Questions