In this article, we’re going to learn how to change Swagger base uri in ASP.NET Core Web API.
So let’s start.
Swagger and Base Uri
Swagger is an open-source framework that helps us design, build, document, and consume RESTful Web services. It provides us with clear and detailed documentation of API endpoints and their expected inputs and outputs. This leads to an easier way to share and maintain our web services. To learn more about swagger, see Configuring and Using Swagger UI in ASP.NET Core Web API.
When we use Swagger in our applications, by default Swagger UI is served at http://localhost:<port>/swagger/index.html. Also, the swagger definition JSON file, which the Swagger UI uses to generate the API documentation is by default at
http://localhost:<port>/swagger/swagger.json.
There are multiple reasons why we would want to change these URLs, some of them are:
- Customization
- Security
- Uri Conflict
Let’s now see how to achieve it.
Modify a Base URI of Swagger
In Visual Studio, we will create a new ASP.NET Core Web API project. By default, it creates a sample Weather Forecast project, and Swagger is already integrated into it.
After we create our project, let’s check what we have by default in our Program.cs:
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
UseSwagger and UseSwaggerUI are methods we use to configure Swagger and SwaggerUI middlewares. If we don’t modify them, when starting the app we land at the default base uri for Swagger UI.
Let’s say we want to customize our Swagger, and we want our Swagger UI base uri at http://localhost:<port>/codeMaze/index.html, and our swagger json file located at localhost:<port>/codeMaze/swagger.json.
First, let’s change the Swagger UI uri:
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(option =>
{
option.RoutePrefix = "codeMaze";
});
}
We use the RoutePrefix option in UseSwaggerUI middleware, where we specify the uri prefix we want to use. Since our desired outcome is http://localhost:<port>/codeMaze/index.html, we assign it "codeMaze" value.
Now, our Swagger UI is served at this uri, but when we start the app, it goes to the default route and not the one we set in middleware.
To change it, let’s open the launchSettings.json file, which is located in the Properties folder. Here, we are going to set the launchUrl property to have the same value as the RoutePrefix property, in our case "codeMaze":
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"launchUrl": "codeMaze",
"applicationUrl": "http://localhost:5108",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
Now let’s get back to the Program class to modify our swagger.json file uri:
if (app.Environment.IsDevelopment())
{
app.UseSwagger(option =>
{
option.RouteTemplate = "codeMaze/{documentName}/swagger.json";
});
app.UseSwaggerUI(option =>
{
option.SwaggerEndpoint("/codeMaze/v1/swagger.json", "CodeMaze API");
option.RoutePrefix = "codeMaze";
});
}
To customize the swagger.json file uri, we modify both UseSwaggerUI and UseSwagger middlewares.
In UseSwaggerUI we change the SwaggerEndpoint property, which allows us to change uri where json file is located. Also, this option has a required parameter name, so we name our Swagger API "CodeMaze API".
However, the SwaggerEndpoint option alone is not enough to change the uri of the Swagger specification. Therefore, we also modify the RouteTemplate in UseSwagger middleware, which specifies the URL template for serving the swagger.json file. We set it to our desired "codeMaze" value, and following Swagger standards, it also contains {documentName} property in the route.
Finally, if we start our application we will land at http://localhost:<port>/codeMaze/index.html with our swagger.json file located at localhost:<port>/codeMaze/swagger.json.
Conclusion
In this article, we learned about different use cases in which we would want to change the base uri of our Swagger. Also, we saw how to change the base uri of our swagger UI and how to do the same for the swagger.json file.
