Swashbuckle.webapi: Swashbuckle 5 pre not working with my WebApi 2

[Danillo1969]

I'm developing a WebApi2 project in VS2013. So installed the "Swashbuckle -pro" NuGet and tried to follow the instructions in the documentation to the the API documented. I have XML-Comments switched on and the main page /swagger shows up but no additional documentation is shown even when the XML-files are present in the bin/ directory.

Does anyone have an idea why I can run the swagger main page but don't get the docs part?

[pareshnawale]

Have you configured XML documentation in Swagger config like below?

SwaggerSpecConfig.Customize(c =>
{
c.IncludeXmlComments(GetXmlCommentsPath());
}

[Danillo1969]

Yes I did

Am 13.02.2015 um 17:50 schrieb pareshnawale <[email protected][e-mail]>:

Have you configured XML documentation in Swagger config like below?

SwaggerSpecConfig.Customize(c =>
{
c.IncludeXmlComments(GetXmlCommentsPath());
}

Reply to this email directly or view it on GitHubhttps://github.com/domaindrivendev/Swashbuckle/issues/184#issuecomment-74285164.

[Danillo1969]

Any other ideas?

[domaindrivendev]

You'll need to give me a little more information to work with - perhaps a screen shot would help.

Just to be clear, are you saying that the swagger page loads correctly and you can try out the different operations etc. but you just don't see the additional description fields populated from your XML comments?

Or is their a problem with the page in general when you have XML comments wired up through SwaggerConfig.cs?

[Danillo1969]

Hi domaindrivendev,

Attached see a screenshot. The blured part of the screenshot is the namespace name (confidential).

As you can see the swagger page shows (IMO) correctly, but no content of the XML-documentation I activated shows up. So nothing can really be done on the swagger page.

What I did by now:

1. Added Swashbuckle NuGet package
2. Activated XML-documentation in the project
3. Added a sample comment (Summary) in one ApiController
4. Tried the setting in the web.config (e.g. vs.EnableBrowserLink and runAllManagedModulesForAllRequests)
5. in SwaggerConfig.cs added the line 'c.SingleApiVersion', 'c.IncludeXMLComments' and 'c.EnableOAuth2Support'
6. Method 'GetXMLCommentsPath' points to the path for the main Api-XML file in the 'bin' directory

May I have to register the SwaggerConfig with the HttpConfiguration?

[gzinger]

Before XML comments start to appear, you need to make sure that any controllers and their methods show up on that page.

1. Why does your path to the documentation has /10 at the end of the URL?
2. Also, is the library you are trying to document in the same project that you trying to use SB from? I had a similar issue when my class library was in a separate project and SB didn't see any of its controllers.

[domaindrivendev]

At this point we should figure out if this is a swagger generation error or a swagger-ui error.

Can you navigate directly to the discovery URL - http://localhost:50992/swagger/docs/10. This should return the raw swagger JSON. Have a read though it and ensure it looks correct. You can also check to see if your XML descriptions are included

Also, when you render the UI, can you open up your JS console to see if there are any JS errors. If so, can you forward on the stack trace. Thanks

[Danillo1969]

Hi gzinger,

1. The /10 is because I defined a single API version with version number set to 10. And the link is showing by default from swagger
2. The library is in the same project. I check that at the begining

[Danillo1969]

Hi domaindrivendev,

When typing in the link you suggested following json appears:

{"swagger":"2.0","info":{"version":"10","title":"xxxxxx.Api"},"host":"localhost:50992","schemes":["http"],"paths":{},"definitions":{}}

In my console when running the UI as shown before I get following output:

[domaindrivendev]

So, "paths" is empty which ultimately means that for some reason, WepApi's built in metadata layer (ApiExplorer) is not reporting any of your API routes.

This may sound stupid but just need to double-check ... I assume you've confirmed your API routes are wired up correctly and working independent of Swashbuckle.

Another possibility, some OData controller types (e.g. EntitySetController) are not correctly reported by ApiExplorer and hence Swashbuckle - https://aspnetwebstack.codeplex.com/workitem/1892

Are you per chance inheriting from these controllers?

[Danillo1969]

I inherit the controllers from ApiController. The routes seem to work because accessing them e.g. via Postman works.

I'm also not using any OData controllers. We use OAuth for authorization, but I assume this has nothing to do with my problem viewing the API.

[Iloshka]

I got similar issue with MVC 5.I upload my test project here. http://www.filedropper.com/testapi
Routes are empty, but i can access method on controller

[domaindrivendev]

As I still can't repro this, could one of you guys put a break point in a controller and check what comes back from the following line:

var apiDescriptions = Request.GetConfiguration().GetServices((.GetApiExplorer().ApiDescriptions

On a bus and above is from memory so may need to google it.

SB is built on top of this built-in metadata layer and I want to confirm there is no issue there

Thanks

[Danillo1969]

Sorry I'm not so experienced in this configuration stuff. Where do I have to place the call mentioned? Where do I get a 'request' object from? I googled and found that GetApiExplorer needs a ServiceContainer. No idea where I get this from.

[Iloshka]

I got array of 2 ApiDescription of my 2 controllers, by using this in method.
GlobalConfiguration.Configuration.Services.GetApiExplorer().ApiDescriptions

[remiplanglois]

From the project http://www.filedropper.com/testapi

[Danillo1969]

I get an item of type System.Collections.ObjectModel.Collection returned and it has Count = 0. So there is nothing loaded.

[domaindrivendev]

So, to summarize ...

@Iloshka - you see your controller actions in ApiExplorer but not Swashbuckle?

@remiplanglois - you are seeing your actions in ApiExplorer. Are you also having an issue with SB? I've noticed that your path is incorrect. This is because (from what I gather) you're using a custom controller selector for name-spaced routes. This approach is known to break ApiExplorer. Attribute routing is the recommended (and much simpler) way to implement API versioning.

@Danillo1969 - you are not seeing your controller actions in ApiExplorer? This means there is some other reason, independent of Swashbuckle, that's causing your issue

[domaindrivendev]

@Iloshka - have you tried viewing the raw swagger docs to ensure this isn't just a UI rendering/JS issue.

/swagger/docs/v1

You could also check the JS console for Javascript errors?

[Iloshka]

yes, raw docs is working.
producing
{"swagger":"2.0","info":{"version":"v1","title":"TestAPI"},"host":"localhost:11251","schemes":["http"],"paths":{"/api/v1/countries":{"get":{"tags":["CountriesV1"],"operationId":"CountriesV1_Get","consumes":[],"produces":["application/json","text/json","application/xml","text/xml"],"responses":{"200":{"description":"OK","schema":{"type":"string"}}},"deprecated":false}},"/api/v2/countries":{"get":{"tags":["CountriesV2"],"operationId":"CountriesV2_Get","consumes":[],"produces":["application/json","text/json","application/xml","text/xml"],"responses":{"200":{"description":"OK","schema":{"type":"string"}}},"deprecated":false}}},"definitions":{}}

im getting js error in shred-bundle-js
Cannot find module zlib

[Iloshka]

Ok /swagger/docs/v1 generate docs only when SingleApiVersion in use, and it expose documentation for 2 versions. When MultipleApiVersion, no docs generated

[domaindrivendev]

@Iloshka - when you use MultipleApiVersions, you have to provide a lambda that will inform SB if a given ApiDescription should be displayed for a given version. There are many ways to implement versioning in WebApi (attribute routing being my go-to) and so this lambda must reflect the specific approach used in your app.

From what you've described, it sounds like there may be an issue with the lambda you're passing to do this. Could you let me know how you're implementing versioning and also share your implementation for the lambda that is passed to MultipleApiVersions?

[Iloshka]

Thank you so much, now i understand what need to be done.
I fixed my lambda function and now it works as expected.

Here is my implementation

                    c.MultipleApiVersions(
                        (apiDesc, version) =>
                        {
                            var controllerNamespace = apiDesc.ActionDescriptor.ControllerDescriptor.ControllerType.FullName;
                            if (CultureInfo.InvariantCulture.CompareInfo.IndexOf(controllerNamespace, string.Format("{0}Controller", version), CompareOptions.IgnoreCase) >= 0)
                            {
                                return true;
                            }

                            return false;
                        },
                        (vc) =>
                        {
                            vc.Version("v2", "Swashbuckle Dummy API V2");
                            vc.Version("v1", "Swashbuckle Dummy API V1");
                        }
                        );

[Danillo1969]

Hi domaindrivendev,
In the meanwhile I set up a fresh webapi project, integrated the newest Swashbuckle verson 5.0.1. and added a sample ApiController with XML-Documentation enabled (in the project settings and in the SwaggerConfig.cs). So this works fine and I can see the API and the comments.

Then I went back to my productive code and had some success, adding the httpConfiguration.EnableSwagger(c => c.SingleApiVersion("v10", "MyApi")).EnableSwaggerUi(); to the Startup.cs of my OWIN middleware. This is besides the SwaggerConfig.cs having the same information extended by the XmlComment path and the OAuth stuff. When I open the Swagger UI I get the API with all the PUT/GET/POST stuff, but the comments I added in the code don't show up as in the sample I set up.

I then also tried to uninstall the prerelease package I first used with my productive code and installed the official version 5.0.1. which didn't work at all.

So what could be the problem now? I'm also not so happy with the mixture of SwaggerConfig and the settings in the Startup. This looks to me like a hack.

[domaindrivendev]

There should not be a mix of settings. Please read the Getting Started section in the readme, particularly the section on OWIN.

Here you'll see that in an OWIN environment you install Swashbuckle.Core directly and not Swashbuckle, the latter being a convenience package for IIS hosted only. This way, you dont get SwaggerConfig.cs. Instead you just manually configure (including XML comments) in your Startup.cs.

[domaindrivendev]

Or, you can remove the preapplicationstartup (as it doesn't work with OWIN) tag from SwaggerConfig and have its Register method accept a HttpConfiguration object instead of using GlobalConfiguration. The finally, invoke this method from your Startup class

[Danillo1969]

Now I have set up a sample project having everything in it as the production code has. It uses OWIN, CORS and Swashbuckle as explained for OWIN. The only differences now are:

Production code additionally:

• uses Autofac (Autofac ASP.NET Web API 2.2 Integration, Autofac WCF Integration, Autofac)
• in the Configuration method of the Startup class I'm adding the DependencyResolver to the httpConfiguration (DependencyResolver is an Autofac container with ApiControllers and WCF Endpoints registered)

Still the production code doesn't work. It now shows a 404 error when swagger ui is started. The XML files for API description are available as in the sample project. The sample project runs.

Any idea what goes wrong?

[domaindrivendev]

Did you every get this resolved? What URL are you using to navigate to the swagger-ui?

[replaysMike]

I'd like to know myself as I'm stuck in the same boat. Actually, we're probably driving very similar boats but with the same result. I created an MVC5 WebAPI 2 app, versioned using http constraints and got further along thanks to a few threads in here. I haven't looked at the OWIN specific requirements for swashbuckle yet.

In my case, I get a full list of routes back from the ApiDescriptions call suggested a few comments above, and they are also in the JSON response that swagger calls. That's great, which means I configured MultipleApiVersions() correctly, and the XmlComments file is correct. The swagger UI however throws a null ref error "Cannot read property 'tags' of null" on line 484 of the swagger-client.js. It looks to be expecting that all of the http verb objects inside the response.paths[path] should not be null.

Here's what my internal JS object looks like (JS debugger) on a controller that only handles a post method:

response.paths[path]={$ref: null
delete: null
get: null
head: null
options: null
parameters: null
patch: null
post: Object { ... }
put: null
vendorExtensions: Object
}

Swagger should be doing a null check here. Sure would be nice if I had a way to supply a custom swagger-client.js! But besides that point, maybe my data is not as expected. Suggestions?

[replaysMike]

I just read your comment above DDD, about registering it properly for OWIN. The correct answer, I'm assuming is not to register Swagger from your startup class, but your Global.asax using:
GlobalConfiguration.Configure(WebApiConfig.Register);
GlobalConfiguration.Configure(SwaggerConfig.Register);
AreaRegistration.RegisterAllAreas();
.... and so on

after modifying the Register method to take in an HttpConfiguration.
Though I'm not sure this addresses any of the problems here.

[Danillo1969]

@domaindrivendev: No I didn't get any further with this. I'm still assuming there is something in the way when using Autofac in my project. That's so far the only difference between my production code and the test project I set up. I will look into this during the next few days and will come back with my findings.

[Danillo1969]

@replaysMike: I'm not sure if we are in the same boat. I'm not using MVC, only WebApi2. Do you work with Autofac too? If this is the case, this might be the root of the problem.

[replaysMike]

I'm using both MVC 5 and WebApi2 in the same project. It shouldn't be relevant, the MVC part as it just includes different libraries but the overall configuration is similar. OWIN might be making a difference, but I don't seem to have any OWIN specific issues even with the standard installation method (tried both after reading docs, now I only have core installed).

I don't use Autofac, was previously using StructureMap but not in this project. Dan - do you get a javascript console error when you visit the swagger ui? I'm hoping we are encountering the same issue.

In case it helps, I uploaded my json response: link JSON

[Danillo1969]

@replaysMike: Mike, I don't get a console error with my test project that doesn't use Autofac. I uploaded the solution, so you can try if this works on your machine. See https://www.dropbox.com/s/79epf3i5ph6povw/Swagger.zip?dl=0

[replaysMike]

Thanks I will check it out, calling it a night but I will test it first thing in the morning. Hopefully the dev will chime in tomorrow.

[replaysMike]

Dan I think I see the problem with your configuration, I'll post in a little while the solution if it works.

[replaysMike]

Sorry I was mistaken, Swaggler seems to work fine in the solution you sent me without any issues, though you should upgrade the core NuGet package to 5.03. Was there something that wasn't working for you in that project?

[replaysMike]

If you have a project with Autofac and it isn't working, feel free to send it to me and I can help look for issues. Unfortunately, it seems we are having different problems. I'm going to create a new project and see if I can find what is causing my issue.

[domaindrivendev]

@replaysMike see above - created a new ticket for your issue as it's a different problem.

[Danillo1969]

@domaindrivendev: just to let you know, yesterday I updated my production code with the newest NuGet packages, including the Swashbuckle.Core 5.0.4. The other packages were the ones around MS WebApi 2.2, Owin, Cors. And now it seems to work with the swagger UI. No idea why. Maybe due to the Swashbuckle update?

[domaindrivendev]

That's awesome - good enough to call it a wrap on this issue I think :)

Thanks for persevering and let me know if you encounter any more issues

[Danillo1969]

Thank you too for the support. Will come back if we encounter any other issues.

[swood36584]

@Danillo1969: I think I know what your issue is. I had the same problem. You are configuring Swashbuckle on the wrong HttpConfiguration instance.
In SwaggerConfig, you are probably using GlobalConfiguration.Configuration.EnableSwagger...
The GlobalConfiguration.Configuration instance is not the same one that is used in your OWIN startup class, which you probably "new" up yourself, as in "var config = new HttpConfiguration();"
That's why when you copied the code to the StartUp class, you switched to the correct HttpConfiguration and had success with it.
This has bitten me a few times :-)

[solo812]

@swood36584 : Thanks for the pointer. I am having the same issues as @Danillo1969 and I also use OWIN. Could you share a sample of the code that you have running in your Startup.cs file? I am a bit lost and could use a little help.

Thanks.

[solo812]

I managed to get it working by following the thread at: https://github.com/domaindrivendev/Swashbuckle/issues/196

Thanks.

[draxtor]

I had the same issue and what @swood36584 said solved it.
I commented the line [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]
Modify Register method to accept HttpConfiguration object and now I'm calling it from statup.cs

[andrenpt]

Thanks @draxtor. I have done the same and it's working fine

[carlosdarienvizcaino]

@Danillo1969 @domaindrivendev I had a very similar problem Danilo was having and httpConfiguration.EnableSwagger(c => c.SingleApiVersion("v10", "MyApi")).EnableSwaggerUi(); solved it for me. Now, I don't understand why I have to do this at the Startup.cs file. I though SwaggerConfig.cs was suppose to be responsible for swagger configuration responsibilities.