Update Swashbuckle to support swagger-ui 3.x

[munnaonc]

Current supported Swagger UI by Swashbuckle is 2.x. However, Swagger UI has moved to 3.x and have lots of bug fixes.

Any Planned update would be greatly appreciated.

[heldersepu]

I was checking out Swagger UI 3.x: http://petstore.swagger.io/ and it seems to have some missing features:

• no direct link to controller or action
• no field to add a body to the POST action
• Try the /pet/findByStatus select "available" and execute the loading shows and after a few it crashes the browser.

I'm not too convinced that version is stable

[danpetitt]

Doesnt crash the browser for me, it just returns a lot of items which causes issues; its much better when setting response type to JSON; but set it to XML and it takes an age and uses a lot of ram.

[heldersepu]

@coderangerdan What about the other issues that I mentioned?

[heldersepu]

That missing direct link to controller or action bothers me... It used to be that you click on a controller and that will show in the URL

I send a direct links to my actions all the time, like this http://swashbuckletest.azurewebsites.net/swagger/ui/index#!/Default/Default_Get If they remove that I guess I will have to fork the Swagger-UI project

[danpetitt]

That is a bit strange, looks like a regression problem; but the other things it fixes bother me more personally.

[heldersepu]

Comparing version 3.x with 2.x I see they are quite different: https://github.com/swagger-api/swagger-ui/tree/master/src https://github.com/swagger-api/swagger-ui/tree/2.x/src/main That will probably create issues on our side...

Also there is a long list of known bugs for 3.x see: https://github.com/swagger-api/swagger-ui/issues?q=is%3Aopen+is%3Aissue+label%3A3.x+label%3ABug Maybe we should wait until that list is down to a handful.?

[danpetitt]

Entirely down to, but i would probably agree :-) thanks

[heldersepu]

I've been working on my fork, I updated to the latest Swagger-UI (3.x), here is how it looks on one of my projects: http://turoapi.azurewebsites.net/swagger/ui/index

If you have time I could use your help testing it, you can get my version from MyGet: https://www.myget.org/feed/heldersepu/package/nuget/Swagger-Net

[domaindrivendev]

@munnaonc - as awesome as swagger-ui 3.x is, there's still known issues and feature gaps in comparison to 2.x.

Therefore, updating SB to use it may result in an overall regression of SB functionality. Ideally, with any upgrade of the swagger-ui, I'd like to maintain feature parity and then some. So, I don't feel it's the right time to make this change right now.

However, the swagger-ui is essentially just set of static files (HTML, CSS, JS etc.) that you can easily expose with any web server (IIS, apache, nginx, S3 etc.). So, it would be fairly trivial to host this yourself and just leverage SB for the Swagger generation and corresponding Swagger JSON endpoint.

[whippet-rider]

Makes sense to me to stay with the non 3.x version. It looks pretty and new, but...

[munnaonc]

@domaindrivendev Thanks for taking the time to review and considering various scenarios. I understand Swagger UI 3.x does look completely different to what we have in Swagger UI 2.4x. So it's your call to update or not, or perhaps wait a couple of months before Swagger 3.x have a more professional look and fewer bugs. Thanks again.

[calvin998]

Just want to check the status of upgrading to Swagger UI 3. I'm waiting for this fix: https://github.com/domaindrivendev/Swashbuckle/issues/1127 (Display Inline Model). Thanks!

[Kizmar]

I was looking for a fix to this as well. Response type of application/pdf (among others) is encoded improperly and results in corrupt downloads.

[vytautas-pranskunas-]

Any progress on this?

[gingters]

How is the state of this? It's quite old by now, and issues with Swagger UI 2 are starting to pile up.

[rfrancisco]

Any news regarding this?

[csutorasr]

It has a preview available. https://github.com/domaindrivendev/Swashbuckle.AspNetCore/pull/543#issuecomment-359574309

[Cloudmersive]

Come on guys! This is important!

[capworks]

I was able to find a really easy workaround for this problem using this method:

https://github.com/domaindrivendev/Swashbuckle#provide-your-own-index-file

I used the following HTML:

<html> <head> <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui-bundle.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui-standalone-preset.js"></script> <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui.css"> </head> <body> <div id="swagger-ui"></div> <script> const ui = SwaggerUIBundle({ url: "https://[API ROOT URL HERE]/swagger/docs/v1/", dom_id: '#swagger-ui' }) </script> </body> </html>

Worked like a charm and displays the interface much faster than before.

So I'm not really sure why this issue has taken so long to implement?

[lineker]

@capworks thanks for your solution. I also added the following lines to get the Bearer token hack working.

    ui.authActions.authorize = function (authorization) {
        authorization.apiKey.value = "Bearer " + authorization.apiKey.value;
        console.log("authorized with bearer token : " + authorization.apiKey.value);
        originalAuthorize(authorization);
    };```

[curiousdev]

Folks still interested, I've submitted the following pull-request to get swagger-ui updated.

https://github.com/domaindrivendev/Swashbuckle/pull/1304

[AndiRudi]

@capworks I tried your solution and the swagger ui 3 displays but I can't get the token to be sent. It works with swagger ui 2 where I have the following setup for api key (jwt token):

swagger.ApiKey("Token")
   .Description("Filling bearer token here")
   .Name("Authorization")
   .In("header");

and

 c.EnableApiKeySupport("Authorization", "header"); //Does this work only for swagger ui 2?

I can click the Authorize Button and add the token, but when I execute a call it's just not added.. Any ideas?

[prusswan]

Using custom index file until #1304 is merged

[kalleguld]

@AndiRudi You need to tell Swashbuckle which operations need security. EnableApiKeySupport() would use the api key for all calls, but Swagger UI 3 will only use auth for the calls that need it.

I put an attribute on all my operations that need auth, [ApiKeyAuthorize] Here's the code to support it:

[AttributeUsage(AttributeTargets.Method)]
public class ApiKeyAuthorizeAttribute :SwaggerOperationFilterAttribute
{
    public ApiKeyAuthorizeAttribute() : base(typeof(ApiKeyAuthorizeFilter)) { }
}

public class ApiKeyAuthorizeFilter : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        if (operation.security == null)
            operation.security = new List<IDictionary<string, IEnumerable<string>>>();

        operation.security.Add(new Dictionary<string, IEnumerable<string>> { 
            { "Token", new List<string>() } //Use the appropriate api key name as set in swagger.ApiKey()
        });
    }
}

[ByYogi]

I've been working on my fork, I updated to the latest Swagger-UI (3.x), here is how it looks on one of my projects: http://turoapi.azurewebsites.net/swagger/ui/index

If you have time I could use your help testing it, you can get my version from MyGet: https://www.myget.org/feed/heldersepu/package/nuget/Swagger-Net

@heldersepu And you, my friend, you're a real hero.

[heldersepu]

@heldersepu And you, my friend, you're a real hero.

Appreciate that @ByYogi ... I stand on the shoulder of many heroes that cloned committed and pushed before me