Swashbuckle 5 can't find my ApiControllers

问题:

I'm at a point where I really need API documentation for my WebAPI 2 project, and I used the Swashbuckle 5 NuGet package. Out of the box, I can hit {myrooturl}/swagger and a UI pops up, but there are no controllers, methods, or anything in there. Just my title: [ base url: /EM.Services , api version: v1 ]

I took a look at the Swashbuckle docs, and since I'm using OWIN which is hosted by IIS, I modified the SwaggerConfig with:

c.RootUrl(req => req.RequestUri.GetLeftPart(UriPartial.Authority) + req.GetRequestContext().VirtualPathRoot.TrimEnd('/'));

as per this doc: https://github.com/domaindrivendev/Swashbuckle/blob/1326e753ce9b3a823b3c156b0b601134692ffc58/README.md#transitioning-to-swashbuckle-50

I also setup the build of the project to generate the XML docs and pointed my SwaggerConfig to it with:

    private static string GetXmlCommentsPath()
    {
        // tried with an without the \bin
        return String.Format(@"{0}\bin\EM.Services.XML", AppDomain.CurrentDomain.BaseDirectory);
    }

I'm not sure if the XML docs working/not-working has anything to do with it though, as I get absolutely no controllers on the swagger-ui page.

For what it's worth, all of my controller inherit from a BaseController, which in turn inherits from ApiController.

Is there something screwy with my WebApiConfig?

    public static void Register(HttpConfiguration config)
    {

        config.SuppressDefaultHostAuthentication();
        config.Filters.Add(new HostAuthenticationFilter(OAuthDefaults.AuthenticationType));

        config.Filters.Add(new ValidateModelAttribute());

        config.Filters.Add(new BaseAuthenticationAttribute());

        config.MapHttpAttributeRoutes();

        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{action}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );

        var jsonFormatter = config.Formatters.OfType<JsonMediaTypeFormatter>().First();
        jsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
        jsonFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/html"));
    }

My concrete controllers all look like this (I've tried subbing out BaseController for ApiController and there is no change):

[RoutePrefix("api/whatever")]
public class FooController : BaseController

and my Base controller doesn't do much (yet), just has an attribute:

[BuildClaims]
public abstract class BaseController : ApiController

The empty page persists across using IIS Express or full blown IIS.

Update: Example of a contrived controller I made that is really basic. It also does not show up, as I still have the boiler plate swagger ui with nothing in it.

/// <summary>
/// I am a test
/// </summary>
[RoutePrefix("api/dummy")]
public class DummyController : ApiController
{
    [HttpGet]
    [Route("foo")]
    public int Foo()
    {
        return 42;
    }
}

回答1:

I got stuck.. and these answers didn't help me fully... although they led me there. Just to save other people some time:

You have to pass the http config from OWIN and then register on that instead of using the GlobalConfiguration class like so:

//starup.cs
public void Configuration(IAppBuilder app)
    {
        Config = new HttpConfiguration();
        WebApiConfig.Register(Config);

        app
            .UseResponseLogging()
            .UseRequestLogging()
            .UseHttpErrors()
            .UseExceptionLogging()
            .UseWebApi(Config);

        HandlerConfig.Register(Config);

        SwaggerConfig.Register(Config);
    }

and in the swagger config file, change the register method to:

public static void Register(HttpConfiguration config)
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        config
            .EnableSwagger(c =>
                {...

Hope this helps.

回答2:

I found the problem. After creating an empty test project, I noticed that the WebApiConfiguration was being registered from the global.asax app start and not the OWIN startup class (like I did).

Since Swagger/Swashbuckle is hooking into the GlobalConfiguration and also given that OWIN startup and Global.asax live in different contexts (I think), the fix is to wire up your WebAPI stuff to register from Global.asax and to have OWIN's app object use WebAPI.

Relevant bits:

   // global asax
    protected void Application_Start(object sender, EventArgs e)
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
       // ... more stuff
    }

   //startup.cs
   public void Configuration(IAppBuilder app)
    {
        // This must happen FIRST otherwise CORS will not work.
        app.UseCors(CorsOptions.AllowAll);

        HttpConfiguration config = new HttpConfiguration();

        ConfigureAuth(app);

        // webapi is registered in the global.asax
        app.UseWebApi(config);

    }

After rewiring as above, I can now see controllers & actions in swagger UI.

回答3:

I found that I had the same issue. I created an extension method to help

using Swashbuckle.Application;
using System.Web.Http;

public static class SwaggerExtensions
{
    public static HttpConfiguration EnableSwagger(this HttpConfiguration httpConfiguration)
    {
        httpConfiguration
            .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API"))
            .EnableSwaggerUi();
        return httpConfiguration;
    }
}

Then in my Startup.cs

public class Startup
{
    public void Configuration(IAppBuilder appBuilder)
    {
        HttpConfiguration httpConfiguration = new HttpConfiguration();

        httpConfiguration
            .EnableSwagger()    // <==== EXTENSION METHOD <==== //
            .MapHttpAttributeRoutes();

        httpConfiguration.Routes.MapHttpRoute(
            "DefaultApi",
            "api/{controller}/{id}",
            new {id = RouteParameter.Optional});

        appBuilder
            .UseWebApi(httpConfiguration);
    }
}

回答4:

All these solutions works for me, but all of them are just nasty hacks for my issue. After few hours of investigation I found out, that the problem is I also use Glimpse (or other packages which change route table).

Here is a great summary: https://github.com/domaindrivendev/Swashbuckle/issues/468#issuecomment-139246748

1. Glimpse adds castle proxies on top of HttpWebRoute. So HostedHttpRouteCollection is collection of RouteProxy and not HttpWebRoute.
2. APIExplorer class has FlattenRoutes method which does a foreach loop over HostedHttpRouteCollection.

3. GetEnumerator implementation of HostedHttpRouteCollection specifically look for HttpWebRoute. See the code below. Since glimpse has added proxies, enumerator always returns 0 routes!!

   public override IEnumerator GetEnumerator()
   {
        // Here we only care about Web API routes.
        return _routeCollection
            .OfType()
            .Select(httpWebRoute => httpWebRoute.HttpRoute)
            .GetEnumerator();
   }

I am affraid there is no solution, you can choose what you want to use: Swashbuckle or Glimpse, but not both together.

Of course you can try to run on one of these workarounds, but there is a risk of unexpected behaviour and tricky bugs.

回答5:

I just had the same issue myself and none of these helped me.

After some messing around I figured out that the routes that I'd labeled as [System.Web.Mvc.Route("visit")] were not being discovered by swagger.

    [HttpGet]
    // ROUTE ATTRIBUTE NOT FOUND BY SWAGGER
    [System.Web.Mvc.Route("visit")]
    public string Visit()
    {

but [System.Web.Http.Route("visit")] is

    [HttpGet]
    // ROUTE ATTRIBUTE *IS* FOUND BY SWAGGER
    [System.Web.Http.Route("visit")]
    public string Visit()
    {

I'm not 100% sure, but if it matters, I also switched from

 public class MyAPIController : Controller

to:

 public class MyAPIController : System.Web.Http.ApiController

More accurately I removed the "using" statement for System.Web.Mvc, but the code is listed for illustrative purposes.

Hope this helps someone else in future :) Good luck!

回答6:

Swashbuckle sits on top of WebApi's metadata layer ApiExplorer. It takes the operation descriptions from ApiExplorer and then maps them to Swagger descriptions.

Since your controller inherits from BASECONTROLLER and not APICONTROLLER it will not work

Per JimWolleys comment

 private IEnumerable<ApiDescription> GetApiDescriptionsFor(string apiVersion)
    {
        return (_options.VersionSupportResolver == null)
            ? _apiExplorer.ApiDescriptions
            : _apiExplorer.ApiDescriptions.Where(apiDesc => _options.VersionSupportResolver(apiDesc, apiVersion));
    }

this is the method that powers Swashbuckle to get all of the api calls. It takes an IApiExplorer. Which if it wasnt modified to take something different it takes the default ApiExplorer provided. Which only has information about things which inherit from ApiController

Swashbuckle git repo. just search for GetApiDescriptionsFor and it will take you straight to the method

回答7:

I had tons of issues with Owin + Swashbuckle integration and none of these answers fixed everything for me. Long story short, I managed to solve everything and created an open source repo to be used as a template for anyone who needs it.

Please check: ASPSwaggerOwinTemplate

回答8:

I found this link to be very helpful. This particular solution is specific to a Microsoft.Azure.Mobile.Server API but it solved the problem for me.

Azure Mobile Apps Server and Swagger