Generating version specific help documentation pages for ASP.NET Web API application

Question

I am using the WebAPI Versioning package to version my API by the X-Api-Header by using the "VersionHeaderVersionedControllerSelector". I am also using the Microsoft.AspNet.WebApi.HelpPage to autogenerate documentation for the APIs. In order for controller versionign to work, they need to be namespaced with the VersionXYZ as the suffix in the namespace so that the "VersionHeaderVersionedControllerSelector" is able to route the request to the appropriate version of the controller like so:

namespace WEBAPI.Api.Controllers.Version1
{ public class ProductsController : ApiController {} }

namespace WEBAPI.Api.Controllers.Version2
{ public class ProductsController : ApiController {} }

This works as intended but when I look at the generated help pages the ApiDescription is including the "VersionXYZ" suffix from the namespace in the ID (GETapi/Version1.Products) and RelativePath(api/Version1.Products) properties. Ideally what I'd like to do is to have a top level help page which just the API Version numbers and drilling in would show the API the normal way i.e. The ApiDescription.ID = GETapi/Products and the ApiDescription.RelativePath = api/Products

Is there a way to achieve this using the Out of the Box APIs or am I going to need to rollout my own implementation of ApiExplorer

Answer 1

Check out this answer Get Help page works with Api Versioning

Make sure you have configure the versioning right, and you need to get a documentation XML file from your project XXXX.Api.v1 project and place it in the bin folder of the XXXX.Api project.