# 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.
```cs
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:
>
> ```csharp
> 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](configure-and-customize-swaggerui.md#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.
```cs
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:
```cs
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:
```cs
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](https://github.com/swagger-api/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:
```cs
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()`:
```cs
services.ConfigureSwagger(options =>
{
options.SetCustomDocumentSerializer();
});
```
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:
```cs
app.UseSwagger(options =>
{
options.SetCustomDocumentSerializer();
});
```
snippet source | anchor