Skip to content

Generate a documentation for an ASP.NET Core Web API using Swagger

Hi everyone! I hope you’re having a great sunday.
Me and my collegue decided this week to rewrite an api made with Laravel Lumen using ASP.NET Core. While doing so, I was wondering wheter some kind of tool existed to help generate the documentation of the API (since we all know writing a documentation is the least fun thing in programming) and I came across Swagger.

Today I will show how you can automatically generate a documentation (with a UI) for your ASP.NET Core Web APIs using Swagger, as well as some configurations you might be intrested in.
The code using in this post is available here.

Creating a Web API

New Project dialog
New Project dialog

Go ahead and create a new ASP.NET Core Web Application project, then choose Web API in the next dialog.
This will spin up a fresh project for you, containing a single example controller ValuesController which we will modify and use. It should look like this:

Swagger (OpenAPI)

From the specifications:

Swagger™ is a project used to describe and document RESTful APIs.

The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.

Basically, Swagger is just a specification file (which is generated or manually written), which can then be used for many applications (e.g. tests, documentation).
One of the tools we will be used is Swagger-UI, which generates a HTML documentation.

In ASP.NET Core?

Fortunatelly, there are many packages to help us integrate swagger to our web api. Two of them are very known:

  • Swashbuckle: Generate beautiful API documentation, including a UI to explore and test operations, directly from your routes, controllers and models.
  • NSwag: An OpenAPI 2.0 and 3.0 a LOT of platforms.

We’ll be using Swashbuckle, which can be easily installed using NuGet Package Manager:

Integrating Swashbuckle

First of all, we have to setup the swagger specification file generation:

This will inject the services Swashbuckle needs to generate it.

We also have to use it in our app:

Lastly, we add the HTML documentation generation:

/swagger/v1/swagger.json is the path to the generated specifications file by default (we will see later how to change it).

If you start debugging and go to localhost:port/swagger you should see:

Swagger UI
Swagger UI

Which honestly, looks magnificent, considering we didn’t do any work.
In the interactive documentation, you can see routes grouped by their controllers (by default) and you can even try requests by clicking “Try it out”.

XML Documentation

Another feature of Swashbuckle is the ability to use the XML documentation of our project to get more informations about the routes.
First, activate the XML documentation by adding this to your csproj file:

Visual Studio will start giving you a warning, saying that X method doesn’t have a XML comment. To suppress it, add <NoWarn>$(NoWarn);1591</NoWarn> in the same PropertyGroup.

You can now start commenting your requests (sorry for the lack of imagination):

Finally, tell Swashbuckle to use the XML documentation file:

Start debugging and enjoy the results.

Swagger UI with XML documentation
Swagger UI with XML documentation

Changing the default routes

If you want to change where the specification file is generated (by default /swagger/v1/swagger/json), Swashbuckle got you covered!

First, we change the route template:

The {documentName} here tells Swashbuckle where to put the version (e.g. /docs/v1/docs.json).

Lastly, we change the end point in the UI:

If you start debugging, you’ll see no changes except in the path where the specification file gets generated, which is now /docs/v1/docs./json.

Also, it’s possible to change the route of the HTML documentation:

You will have to navigate to localhost:port//docs for the interactive documentation.

Annotations

Swashbuckle proposes some useful annotations to enrich documentation.
First, install the appropriate package:

Then tell Swashbuckle to use them:

Operations

SwaggerOperation is a useful attribute where you can set the summary, description, id and the tags of a certain request/route, for example:

The summary is the same as the XML documentation and the description is show under the request (in the interactive documentation).

Responses

SwaggerResponse is an attribute where you can set for each status code a description, for example:

The will show in the Responses part of every request (where the status code 200 is present by default).

Tags

SwaggerTag is an attribute where you can set a tag for a controller, which can be then used to group requests by something other than the controller’s name:

The tag is also shown next to the controller’s name:

Swagger UI with annotations
Swagger UI with annotations

 

This concludes today’s post!
In my opinion, Swashbuckle makes it easier to concentrate on the actual API and leave the documentation writing to it, which honestly it does a great job at.
Richard Morris is doing a great job developping and maintaining the library, it has everything you need and I advise you to use whenever you need it.

Have a good Monday!

Published inProgramming

Leave a Reply

avatar
  Subscribe  
Notify of