Software Engineering Life

Mar 27, 20263 min read

Adding SWAGGER api documentation to your dotnet core api

I started and created an api with no documentation and really wanted to add Swagger UI to it so that I can have interactive documentation to give at anyone who wants to use the api and make the documentation that I would have to write manually, less.

In so, I started to investigate exactly how to go about this and this is what I did to get it working as I wanted it to.

Choosing between Swashbuckle and NSwag

I usually check installs and Last Updated. If it has not been updated in a long time, 1+ years, I would look to the amount of installs, it it still being used a lot, I can oversea it, but not more than 2 years. Then I would take the one which has been updated the latest. If the installs of the one over the other is overwhelming, I would go for the one installed more times as chances are that there will be a lot more information regarding that package.

Using these criteria, it was kind of a landslide in the way of Swashbuckle.

Installing and Setting up the Library

  1. First we need to install the Swashbuckle package using nuget:
Install-Package Swashbuckle.AspNetCore -Version 6.5.0
  1. In the ConfigureServices method of Startup.cs, register the Swagger generator, defining one or more Swagger documents.
using Microsoft.OpenApi.Models;
services.AddMvc();
 
services.AddSwaggerGen(c =>
{
	c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
  1. In your Project Properties under the Start up Project select the project and not IIS.

That’s it, if you start the project, it should open up to the Swagger UI and you should see your endpoints that you have configured.

What Can Go Wrong..

If you are like me you will have some things not done correctly and you will have an endpoint or two set up incorrectly so a shortlist of things to check for:

  • Make sure all endpoints have the appropriate [Http] attribute.
  • Make sure all endpoints are unique and not doubles, as it will cause issues in the generation of the Swagger UI.

Adding More Information to the Endpoints

So you have your Swagger UI running and you give it to someone and they ask, “What is that endpoint for?” because like a good software engineer, you named it “GetTheThingFromThePlace” which make exact sense to you, obviously.

First, add the following two lines as below:

services.AddSwaggerGen(options =>
{
     options.SwaggerDoc("v1", new OpenApiInfo { Title = "Open API", Version = "v1" });
 
+    string xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

Fix any missing using as needed, I needed the Assembly and the Path.

Then, you can add comments to the endpoints using the document comments available in the Visual Studio environment

/// <summary>
/// This is an endpoint that does things for the place
/// </summary>
[HttpGet]
public async <IActionResult> GetTheThingFromThePlace(string weirdParam)
{
	return await servicething.GettingTheThingFromThePlace(weirdParam);
}

By adding <summary> comments, you can add a lot more details and explanations to the endpoint.

I will go into more detail in a different blog post as it can get quite hectic the comments/documentation thing.

Adding Authentication to the Swagger UI

📇 Additional Metadata

Graph View

Backlinks