Skip to content

3 Customizing the swagger ui

Jump to bottom
Helder Sepulveda edited this page Jun 4, 2017 · 2 revisions

The swagger-ui is a JavaScript application hosted in a single HTML page (index.html), and it exposes several customization settings. Swashbuckle ships with an embedded version and includes corresponding configuration methods for each of the UI settings. If you require further customization, you can also inject your own version of "index.html". Read on to learn more.

Customizations via the configuration API

If you're happy with the basic look and feel but want to make some minor tweaks, the following options may be sufficient:

httpConfiguration
    .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API"))
    .EnableSwaggerUi(c =>
        {
            c.InjectStylesheet(containingAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testStyles1.css");
            c.InjectJavaScript(containingAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js");
            c.BooleanValues(new[] { "0", "1" });
            c.SetValidatorUrl("http://localhost/validator");
            c.DisableValidator();
            c.DocExpansion(DocExpansion.List);
c.SupportedSubmitMethods("GET", "HEAD")
        });

InjectStylesheet

Use this to enrich the UI with one or more additional CSS stylesheets. The file(s) must be included in your project as an "Embedded Resource", and then the resource's "Logical Name" is passed to the method as shown above. See Injecting Custom Content for step by step instructions.

InjectJavaScript

Use this to invoke one or more custom JavaScripts after the swagger-ui has loaded. The file(s) must be included in your project as an "Embedded Resource", and then the resource's "Logical Name" is passed to the method as shown above. See Injecting Custom Content for step by step instructions.

BooleanValues

The swagger-ui renders boolean data types as a dropdown. By default, it provides "true" and "false" strings as the possible choices. You can use this option to change these to something else, for example 0 and 1.

SetValidatorUrl/DisableValidator

By default, swagger-ui will validate specs against swagger.io's online validator and display the result in a badge at the bottom of the page. Use these options to set a different validator URL or to disable the feature entirely.

DocExpansion

Use this option to control how the Operation listing is displayed. It can be set to "None" (default), "List" (shows operations for each resource), or "Full" (fully expanded: shows operations and their details).

SupportedSubmitMethods

Specify which HTTP operations will have the 'Try it out!' option. An empty paramter list disables it for all operations.

Provide your own "index" file

As an alternative, you can inject your own version of "index.html" and customize the markup and swagger-ui directly. Use the CustomAsset option to instruct Swashbuckle to return your version instead of the default when a request is made for "index". As with all custom content, the file must be included in your project as an "Embedded Resource", and then the resource's "Logical Name" is passed to the method as shown below. See Injecting Custom Content for step by step instructions.

For compatibility, you should base your custom "index.html" off this version

httpConfiguration
     .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API"))
     .EnableSwaggerUi(c =>
         {
             c.CustomAsset("index", yourAssembly, "YourWebApiProject.SwaggerExtensions.index.html");
         });

Injecting Custom Content

The InjectStylesheet, InjectJavaScript and CustomAsset options all share the same mechanism for providing custom content. In each case, the file must be included in your project as an "Embedded Resource". The steps to do this are described below:

  1. Add a new file to your Web API project.
  2. In Solution Explorer, right click the file and open its properties window. Change the "Build Action" to "Embedded Resource".

This will embed the file in your assembly and register it with a "Logical Name". This can then be passed to the relevant configuration method. It's based on the Project's default namespace, file location and file extension. For example, given a default namespace of "YourWebApiProject" and a file located at "/SwaggerExtensions/index.html", then the resource will be assigned the name - "YourWebApiProject.SwaggerExtensions.index.html". If you use "Swagger" as the root folder name for your custom assets, this will collide with the default route templates and the page will not be loaded correctly.

Clone this wiki locally