configure-and-customize-swaggerui.md

Configuration and Customization of Swashbuckle.AspNetCore.SwaggerUI

Change Relative Path to the UI

By default, the Swagger UI will be exposed at /swagger. If necessary, you can alter this when enabling the SwaggerUI middleware:

app.UseSwaggerUI(options =>
{
    options.RoutePrefix = "api-docs";
});

^{snippet source | anchor}

Change Document Title

By default, the Swagger UI will have a generic document title. When you have multiple OpenAPI documents open, it can be difficult to tell them apart. You can alter this when enabling the SwaggerUI middleware:

app.UseSwaggerUI(options =>
{
    options.DocumentTitle = "My Swagger UI";
});

^{snippet source | anchor}

Change CSS or JS Paths

By default, the Swagger UI includes default CSS and JavaScript, but if you wish to change the path or URL (for example to use a CDN) you can override the defaults as shown below:

app.UseSwaggerUI(options =>
{
    options.StylesPath = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.1/swagger-ui.min.css";
    options.ScriptBundlePath = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.1/swagger-ui-bundle.min.js";
    options.ScriptPresetsPath = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.1/swagger-ui-standalone-preset.min.js";
});

^{snippet source | anchor}

List Multiple OpenAPI Documents

When enabling the middleware, you're required to specify one or more OpenAPI endpoints (fully qualified or relative to the UI page) to power the UI. If you provide multiple endpoints, they'll be listed in the top right corner of the page, allowing users to toggle between the different documents. For example, the following configuration could be used to document different versions of an API.

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");
    options.SwaggerEndpoint("/swagger/v2/swagger.json", "V2 Docs");
});

^{snippet source | anchor}

Apply swagger-ui Parameters

swagger-ui ships with its own set of configuration parameters, all described by the swagger-ui Configuration. In Swashbuckle.AspNetCore, most of these are surfaced through the SwaggerUI middleware options:

app.UseSwaggerUI(options =>
{
    options.DefaultModelExpandDepth(2);
    options.DefaultModelRendering(ModelRendering.Model);
    options.DefaultModelsExpandDepth(-1);
    options.DisplayOperationId();
    options.DisplayRequestDuration();
    options.DocExpansion(DocExpansion.None);
    options.EnableDeepLinking();
    options.EnableFilter();
    options.EnablePersistAuthorization();
    options.EnableTryItOutByDefault();
    options.MaxDisplayedTags(5);
    options.ShowExtensions();
    options.ShowCommonExtensions();
    options.EnableValidator();
    options.SupportedSubmitMethods(SubmitMethod.Get, SubmitMethod.Head);
    options.UseRequestInterceptor("(request) => { return request; }");
    options.UseResponseInterceptor("(response) => { return response; }");
});

^{snippet source | anchor}

Inject Custom JavaScript

To tweak the behavior, you can inject additional JavaScript files by adding them to your wwwroot folder and specifying the relative paths in the middleware options:

app.UseSwaggerUI(options =>
{
    options.InjectJavascript("/swagger-ui/custom.js");
});

^{snippet source | anchor}

Inject Custom CSS

To tweak the look and feel, you can inject additional CSS stylesheets by adding them to your wwwroot folder and specifying the relative paths in the middleware options:

app.UseSwaggerUI(options =>
{
    options.InjectStylesheet("/swagger-ui/custom.css");
});

^{snippet source | anchor}

Customize index.html

To customize the UI beyond the basic options listed above, you can provide your own version of the swagger-ui index.html page:

app.UseSwaggerUI(options =>
{
    options.IndexStream = () => typeof(Program).Assembly
        .GetManifestResourceStream("CustomUIIndex.Swagger.index.html"); // Requires file to be added as an embedded resource
});

^{snippet source | anchor}

<Project>
  <ItemGroup>
    <EmbeddedResource Include="CustomUIIndex.Swagger.index.html" />
  </ItemGroup>
</Project>

Tip

To get started, you should base your custom index.html on the built-in version.

Enable OAuth2.0 Flows

swagger-ui has built-in support to participate in OAuth2.0 authorization flows. It interacts with authorization and/or token endpoints, as specified in the OpenAPI JSON, to obtain access tokens for subsequent API calls. See Adding Security Definitions and Requirements for an example of adding OAuth2.0 metadata to the generated Swagger.

If your OpenAPI endpoint includes the appropriate security metadata, the UI interaction should be automatically enabled. However, you can further customize OAuth support in the UI with the following settings below. See the Swagger-UI documentation for more information.

app.UseSwaggerUI(options =>
{
    options.OAuthClientId("test-id");
    options.OAuthClientSecret("test-secret");
    options.OAuthUsername("test-user");
    options.OAuthRealm("test-realm");
    options.OAuthAppName("test-app");
    options.OAuth2RedirectUrl("url");
    options.OAuthScopeSeparator(" ");
    options.OAuthScopes("scope1", "scope2");
    options.OAuthAdditionalQueryStringParams(new Dictionary<string, string> { ["foo"] = "bar" });
    options.OAuthUseBasicAuthenticationWithAccessCodeGrant();
    options.OAuthUsePkce();
});

^{snippet source | anchor}

Use client-side request and response interceptors

To use custom interceptors on requests and responses going through swagger-ui you can define them as JavaScript functions in the configuration:

app.UseSwaggerUI(options =>
{
    options.UseRequestInterceptor("(req) => { req.headers['x-my-custom-header'] = 'MyCustomValue'; return req; }");
    options.UseResponseInterceptor("(res) => { console.log('Custom interceptor intercepted response from:', res.url); return res; }");
});

^{snippet source | anchor}

This can be useful in a range of scenarios where you might want to append local XSRF tokens to all requests, for example:

app.UseSwaggerUI(options =>
{
    options.UseRequestInterceptor("(req) => { req.headers['X-XSRF-Token'] = localStorage.getItem('xsrf-token'); return req; }");
});

^{snippet source | anchor}

Use MapSwaggerUI with endpoint routing

MapSwaggerUI is an endpoint-routing alternative to UseSwaggerUI. The options API is the same, so all customization examples on this page also apply when using MapSwaggerUI.

app.MapSwagger();
app.MapSwaggerUI("swagger", options => options.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs"));

^{snippet source | anchor}

The main differences are:

• UseSwaggerUI adds middleware directly to the request pipeline and returns IApplicationBuilder.

• MapSwaggerUI maps the Swagger UI via endpoint routing and returns IEndpointConventionBuilder.

• Because MapSwaggerUI returns an endpoint convention builder, you can attach endpoint metadata/conventions (for example, authorization policies) directly to the mapped UI endpoint.

app.MapSwaggerUI("swagger-auth")
   .RequireAuthorization(); // Remember to also add RequireAuthorization to MapSwagger.

^{snippet source | anchor}