Complete Guide to Customizing Swagger UI Base URL in ASP.NET Core

Overview of Swagger UI Base URL Configuration

When integrating Swagger into ASP.NET Core projects, the default UI access path is typically /swagger. However, in real production environments, developers often need to adjust this path according to project architecture or security policies. Based on the latest version of Swashbuckle.AspNetCore, this article delves into how to customize the base URL through configuration.

Core Configuration Method: RoutePrefix Property

Starting from version 4.0.1, Swashbuckle.AspNetCore provides the RoutePrefix property to simplify URL path configuration. This property is part of the SwaggerUIOptions class and allows developers to specify the root path for Swagger UI.

The following basic configuration example demonstrates how to change the Swagger UI access path from the default /swagger to /docs:

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

After configuration, Swagger UI will be accessible at http://<server>/docs. It is important to note that the JSON file path in SwaggerEndpoint usually does not need modification unless the Swagger JSON file generation path is also adjusted.

Advanced Configuration: Complete Path Redirection

In more complex scenarios, developers may need to modify both the Swagger UI and Swagger JSON file paths simultaneously. This can be achieved by combining the UseSwagger and UseSwaggerUI methods for comprehensive configuration.

The following example shows how to move all Swagger-related resources under the /myapi/swagger path:

app.UseSwagger(c =>
{
    c.RouteTemplate = "myapi/swagger/{documentname}/swagger.json";
});

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

This configuration approach is particularly useful for multi-API projects or scenarios where Swagger needs to be integrated under a specific namespace.

Development Environment Configuration Optimization

To enhance the development experience, it is recommended to update the startup configuration in the launchSettings.json file accordingly. This ensures that the browser automatically opens the correct Swagger UI address when starting debugging.

Here is a configuration example:

"profiles": {
    "IIS Express": {
        "commandName": "IISExpress",
        "launchBrowser": true,
        "launchUrl": "myapi/swagger",
        "environmentVariables": {
            "ASPNETCORE_ENVIRONMENT": "Development"
        }
    }
}

Configuration Considerations

When configuring URL paths, the following points should be noted:

1. Version Compatibility: The RoutePrefix property is available in Swashbuckle.AspNetCore version 4.0.1 and above. Earlier versions may require different configuration methods.
2. Path Consistency: Ensure that the JSON file path specified in SwaggerEndpoint matches the actual generated path; otherwise, the UI may fail to load the API documentation.
3. Middleware Order: The registration order of UseSwagger and UseSwaggerUI middleware generally does not affect functionality, but it is advisable to configure them in a logical sequence.
4. Production Environment Considerations: In production environments, additional URL rewriting configurations may be required in conjunction with reverse proxies or load balancers.

Practical Application Scenarios

Customizing the Swagger UI base URL is particularly useful in the following scenarios:

• Multi-Project Integration: When multiple API projects are deployed under the same domain, distinguishing them through different path prefixes.
• Security Policies: Hiding Swagger UI under non-standard paths as a simple security measure.
• Brand Consistency: Aligning API documentation paths with the project's URL naming conventions.
• Version Management: Providing independent documentation access paths for different API versions.

By properly configuring the base URL for Swagger UI, developers can better control the access methods and organizational structure of API documentation, enhancing project maintainability and user experience.