configure-and-customize-redoc.md

Configuration and Customization of Swashbuckle.AspNetCore.ReDoc

Change Relative Path to the UI

By default, the Redoc UI will be exposed at /api-docs. If necessary, you can alter this when enabling the Redoc middleware:

app.UseReDoc(options =>
{
    options.RoutePrefix = "docs";
});

^{snippet source | anchor}

Change Document Title

By default, the Redoc UI will have a generic document title. You can alter this when enabling the Redoc middleware:

app.UseReDoc(options =>
{
    options.DocumentTitle = "My API Docs";
});

^{snippet source | anchor}

Apply Redoc Parameters

Redoc ships with its own set of configuration parameters, all described in the Redoc documentation. In Swashbuckle.AspNetCore, most of these are surfaced through the Redoc middleware options:

app.UseReDoc(options =>
{
    options.SpecUrl("/v1/swagger.json");
    options.EnableUntrustedSpec();
    options.ScrollYOffset(10);
    options.HideHostname();
    options.HideDownloadButton();
    options.ExpandResponses("200,201");
    options.RequiredPropsFirst();
    options.NoAutoAuth();
    options.PathInMiddlePanel();
    options.HideLoading();
    options.NativeScrollbars();
    options.DisableSearch();
    options.OnlyRequiredInSamples();
    options.SortPropsAlphabetically();
});

^{snippet source | anchor}

Note

Using options.SpecUrl("/v1/swagger.json") multiple times within the same UseReDoc(...) will not add multiple URLs.

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.UseReDoc(options =>
{
    options.InjectStylesheet("/redoc/custom.css");
});

^{snippet source | anchor}

It is also possible to modify the theme by using the AdditionalItems property. More information can be found in the Redoc documentation.

app.UseReDoc(options =>
{
    options.ConfigObject.AdditionalItems = new Dictionary<string, object>
    {
        // Configured additional options
    };
});

^{snippet source | anchor}

Customize index.html

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

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

^{snippet source | anchor}

<Project>
  <ItemGroup>
    <EmbeddedResource Include="CustomIndex.ReDoc.index.html" />
  </ItemGroup>
</Project>

Tip

To get started, you should base your custom index.html on the default version.

Use MapReDoc with endpoint routing

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

app.MapReDoc();

^{snippet source | anchor}

The main differences are:

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

• MapReDoc maps ReDoc via endpoint routing and returns IEndpointConventionBuilder.

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

app.MapReDoc("redoc-auth")
   .RequireAuthorization(); // Remember to also add RequireAuthorization to MapSwagger

^{snippet source | anchor}