# 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:
```cs
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:
```cs
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:
```cs
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.
```cs
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][swagger-ui] ships with its own set of configuration parameters, all described
[by the swagger-ui Configuration](https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/configuration.md#display).
In Swashbuckle.AspNetCore, most of these are surfaced through the SwaggerUI middleware options:
```cs
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:
```cs
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:
```cs
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:
```cs
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
```xml
```
> [!TIP]
> To get started, you should base your custom `index.html` on the [built-in version](../src/Swashbuckle.AspNetCore.SwaggerUI/index.html).
## Enable OAuth2.0 Flows
[swagger-ui][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](configure-and-customize-swaggergen.md#add-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](https://github.com/swagger-api/swagger-ui/blob/HEAD/docs/usage/oauth2.md) for more information.
```cs
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 { ["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:
```cs
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:
```cs
app.UseSwaggerUI(options =>
{
options.UseRequestInterceptor("(req) => { req.headers['X-XSRF-Token'] = localStorage.getItem('xsrf-token'); return req; }");
});
```
snippet source | anchor
[swagger-ui]: https://github.com/swagger-api/swagger-ui