configure-and-customize-swagger.md

Configuration and Customization of Swashbuckle.AspNetCore.Swagger

Change the Path for OpenAPI JSON Endpoints

By default, OpenAPI (Swagger) JSON will be exposed at the following route - /swagger/{documentName}/swagger.json. If necessary, you can change this when enabling the Swagger middleware.

Important

Custom routes must include the {documentName} parameter.

app.UseSwagger(options =>
{
    options.RouteTemplate = "api-docs/{documentName}/swagger.json";
});

^{snippet source | anchor}

Note

If you're using the SwaggerUI middleware, you'll also need to update its configuration to reflect the new endpoints:

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/api-docs/v1/swagger.json", "My API V1");
});

If you also need to update the relative path that the UI itself is available on, you'll need to follow the instructions found in Change Relative Path to the UI.

Modify OpenAPI with Request Context

If you need to set some OpenAPI metadata based on the current request, you can configure a filter that's executed prior to serializing the document.

app.UseSwagger(options =>
{
    options.PreSerializeFilters.Add((document, request) =>
    {
        document.Servers = [new OpenApiServer { Url = $"{request.Scheme}://{request.Host.Value}" }];
    });
});

^{snippet source | anchor}

The OpenApiDocument and the current HttpRequest are both passed to the filter, which provides a lot of flexibility. For example, you can add an explicit API server based on the Host header (as shown), or you could inspect session information or an Authorization header and remove operations from the document based on user permissions.

Serialize OpenAPI in the 3.1 format

By default, Swashbuckle.AspNetCore will generate and expose OpenAPI JSON in version 3.0 of the specification. However, if you wish to use the latest version of the OpenAPI specification, you can opt into version 3.1 format with the following option:

app.UseSwagger(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
});

^{snippet source | anchor}

Serialize Swagger in the 2.0 format

By default, Swashbuckle will generate and expose OpenAPI JSON in version 3.0 of the specification, officially called the OpenAPI Specification. However, to support backwards compatibility, you can opt to continue exposing it in the Swagger 2.0 format with the following option:

app.UseSwagger(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

^{snippet source | anchor}

Working with Virtual Directories and Reverse Proxies

Virtual directories and reverse proxies can cause issues for applications that generate links and redirects, particularly if the app returns absolute URLs based on the Host header and other information from the current request. To avoid these issues, Swashbuckle.AspNetCore uses relative URLs where possible, and encourages their use when configuring the SwaggerUI and ReDoc middleware.

For example, to wire up the SwaggerUI middleware, you provide the URL to one or more OpenAPI documents. This is the URL that swagger-ui, a client-side application, will call to retrieve your API metadata. To ensure this works behind virtual directories and reverse proxies, you should express this relative to the RoutePrefix of swagger-ui itself:

app.UseSwaggerUI(options =>
{
    options.RoutePrefix = "swagger";
    options.SwaggerEndpoint("v1/swagger.json", "My API V1");
});

^{snippet source | anchor}

Customizing how the OpenAPI document is serialized

By default, Swashbuckle.AspNetCore will serialize the OpenAPI document using the Serialize* methods on the OpenAPI document object. If a customized serialization is desired, it is possible to create a custom document serializer that implements the ISwaggerDocumentSerializer interface. This can be set on the SwaggerOptions in the service collection using ConfigureSwagger():

services.ConfigureSwagger(options =>
{
    options.SetCustomDocumentSerializer<CustomDocumentSerializer>();
});

^{snippet source | anchor}

Note

If you plan on using the command line tool to generate OpenAPI specification files, this must be done on the service collection using ConfigureSwagger().

When the command line tool is not used, it can also be done on the application host:

app.UseSwagger(options =>
{
    options.SetCustomDocumentSerializer<CustomDocumentSerializer>();
});

^{snippet source | anchor}