How do I change the Swagger default URL and use a custom one?

Question

I have an API that I created in .NetCore 3.1 and have enabled Swagger(OAS3) using Swashbuckle. By default when my app starts if brings up the Swagger page using this URL:

http://{port}/swagger.index.html

I would like to customize the Swagger URL so that it includes the name of the application that is running. The reason I am doing this is because I am using path-based routing with Nginx running in AWS Fargate.

I will have several API containers running in the Fargate task and Nginx will receive the REST requests coming from the Application Load Balancer and from the path (e.g. /api/app1), it will route the request to the correct container port for the target application.

So, for example, I have three apps: App1 on port 5000, App2 on Port 5001 and App3 on port 5003.

If the user makes a request to https://api/app1, Nginx will detect the path and forward the request to port 5000, which is App1's container port.

However, to make sure that the correct Swagger page comes up, I need to add "api/App1" to Swagger's URL so that Nginx will forward the request to the correct container. In this case, it's App1.

In other words, I want my Swagger URL to look like this:

https://api/app1/swagger/index.html

What I've tried

In my Startup.cs file I have added the following:

// Define prefix for application
private readonly string baseApplicationRoute = "api/app1";

            // Enable OAS3 JSON middleware
            app.UseSwagger(c =>
            {
                c.RouteTemplate = baseApplicationRoute+"/{documentName}/swagger.json";
            });


            app.UseSwaggerUI(c =>
            {
                var endpoint = $"/{baseApplicationRoute}/{version.ToLower()}/swagger.json";
                c.SwaggerEndpoint(endpoint, $"APP1 API - {version}");
                c.RoutePrefix = string.Empty;
            });

This compiles and works, however it is still using the same Swagger URL of:

http://{port}swagger.index.html

I think all this is doing is changing the location of the swagger.json because on the Swagger UI that comes up it is showing:

/api/app1/v1/swagger.json

My launchSettings.json file is specifying the "launchUrl" as "swagger".

I think I'm close, but I am obviously missing something. To recap I'm just trying to change:

The default Swagger URL

http://{port}swagger.index.html

To my custom one here:

http://{port}/api/app1/v1/swagger.index.html

That way Nginx can detect "/api/app1" and route to the correct container.

What am i missing?

Solution

I found the solution to this issue:

In the Configure section of Startup.cs I did the following:

First I added the folowing variable:

private readonly string swaggerBasePath = "api/app";

Next I configured the path using UseSwagger and UseSwaggerUI to use the swaggerBasePath variable:

            app.UseSwagger(c =>
            {
                c.RouteTemplate = swaggerBasePath+"/swagger/{documentName}/swagger.json";
            });

            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint($"/{swaggerBasePath}/swagger/v1/swagger.json", $"APP API - {version}");
                c.RoutePrefix = $"{swaggerBasePath}/swagger";
            });

Finally, I modified launchSettings.json to point to the new base path:

    "launchUrl": "api/app/swagger",

Then is was able to hit the Swagger page using:

https://localhost/api/app/swagger/index.html

I testing this with Nginx and it was able to route to the correct container.

I can easily tweak the base path (for instance to add the API version number) by simply modifying the swaggerBasePath variable and tweaking the launchSettings.json file to match the value of the variable.

Hopefully, this will help someone in the future.

Comments

[Guru Stron]

Have you tried setting c.RoutePrefix to baseApplicationRoute?

[Alex Monkey]

Thanks for the solution @KSS. This works nicely for .net core 2.0 + Swashbuckle.AspNetCore v2.5.0 as well.