Documenting DotNet core API’s with swagger

When developing an Application Programming Interface ( API ) for your application it’s important to ensure you provide clear and concise information for developers who you intend to use your API.

This helps them to get up to speed and reduce the learning curve for them to start using and integrating your API into their applications. The primary objective is to remove friction to improve the chances of adoption for your API.

Code on Github

One of the best approaches to this is to develop your documentation as you develop your code. This not only enables you to keep your documentation clear and up to date, but it also ensures you clearly focus on the intent of your code.

Swagger framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API life-cycle, from design and documentation, to test and deployment. Swagger provides an UI representation of your RESTful API. Enabling users to visualize and interact with the API’s resources having none of the implementation logic in place.

To illustrate this approach I’ll use a sample of a project where we have started to implement this approach.

Developing API for other developers and integrator’s to use , you will need to ensure that you supply clear and easy to understand documentation. Documenting or describing your REST API’s doesn’t have to a boring chore , in fact using a framework like swagger makes it really easy.

Swagger

Swagger is an Open Source API Specification Framework, enabling interactive documentation and SDK generation over your Existing REST API.

In this guide I will provide a working example of how to use swagger to start documenting an API. I’ll be starting a brand new development project.

We’ll start off creating a standard DotNet Core Web API project using one of the quick start templates , Create a .net core web application on ubuntu in 5 minutes , as you might guess I am using Ubuntu as my primary development workstation, but the general process of creating a project is the same regardless of operating system.

After creating the project give it a quick test to ensure that all is working as expected.

ddotnet restore dotnet build  dotnet run dotnet restore dotnet build  dotnet run otnet restore dotnet build  dotnet run

We can now browse to the api http://localhost:5000/api/values

Our new very simple API is working!

Swashbuckle.AspNetCore

Swashbuckle combines ApiExplorer and Swagger/swagger-ui to provide a rich discovery, documentation and playground experience to your API consumers. It also contains an embedded version of swagger-ui which it will automatically serve up once Swashbuckle is installed. This means you can complement your API with a slick discovery UI to assist consumers with their integration efforts. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API!

Swashbuckle comprises three packages:

Swagger generator
middleware to expose the generated Swagger as JSON endpoints
A swagger-ui that’s powered by those endpoints.

Swashbuckle.AspNetCore is a release of this library specifically for .net Core API – Check out the GitHub Repository

Add a Reference to the Swashbuckle.AspNetCore library. I do this in Visual Studio Code by adding the Nuget Package Manager extension and then making use of the Command Pallette ( Shift + Ctrl + P ) Nuget Package Manager : Add Package and Search swashbuckle.AspNetCore

You can also add the package making use of the Dotnet Core CLI

dotnet add package swashbuckle.AspNetCore

For more information about using the Dotnet Core CLI to manage package and project references

Once complete we can update our StartUp.cs class with the following code.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Swashbuckle.AspNetCore;
using Swashbuckle.AspNetCore.Swagger;
 
namespace api
{
    public class Startup
    {
         public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }
 
        public IConfigurationRoot Configuration { get; }
 
        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // Add framework services.
            services.AddMvc();
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
            });
        }
 
        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
        {
            loggerFactory.AddConsole(Configuration.GetSection("Logging"));
            loggerFactory.AddDebug();
 
            app.UseMvc();
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            });
        }
    }
}

View Full Code

We can now build and start our API again

dotnet restore
dotnet build 
dotnet run

If we now navigate our browser to http://localhost:5000/swagger we’ll now see the Swagger Ui which is handy for testing your methods and checking their correct responses without needing tools like Postman etc.

Customization

The above example is obviously far too simple for most documentation purposes, and most organisations and projects will require further customization. This is where the real power of Swashbuckle comes in.

Add Developer Details

The first step we’ll take in customizing the details available regarding our API, is to provide further details about who developed the API and some contact details.

In our StartUp.cs we’ll update the ConfigureServices method to include some additional basic contact details

public void ConfigureServices(IServiceCollection services)
        {
            // Add framework services.
            services.AddMvc();
 
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", 
                new Info 
                {
                    Title = "Stop Web Crawlers Update API", 
                    Version = "v1" ,
                    Description = "Stop Web Crawlers Update API to enable the update of Referer Spammer Lists",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "threenine.co.uk", Email ="support@threenine.co.uk", Url ="https://threenine.co.uk"}
                });
              
            }
            
            );
 
         
        }

View Full Code

After this is complete and we restart our project and navigate to the swagger page, our API documentation will now display the general contact information.

Include XML Comment Descriptions

It is usually a good idea to enhance the generated documentation with human-friendly descriptions, usually derived from annotations via XML Comments on Controllers and Models.

We can configure SwashBuckle to incorporate those comments into the Swagger JSON:

Using Visual Studio we can do this by right clicking on the API Project File and selecting Properties then Select the Build tab

Using VS Code we will need to edit and add some additional lines to our .csproj file.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>api.xml</DocumentationFile>
  </PropertyGroup>
  <ItemGroup>
    <Folder Include="wwwroot\" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore" Version="1.0.3" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="1.0.2" />
    <PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="1.0.1" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="1.0.0-rc3" />
  </ItemGroup>
</Project>

Essentially swagger will Create an XML file which will store our comments which will be stored in the whichever directory you choose. I have chosen the root directory of the API, but this path can be anywhere of your choosing just so long as it is accessible when your API is executing.

We’ update our StartUp.cs with some additional information about the developers and contact details for support.

public void ConfigureServices(IServiceCollection services)
        {
            // Add framework services.
            services.AddMvc();
 
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", 
                new Info 
                {
                    Title = "Stop Web Crawlers Update API", 
                    Version = "v1" ,
                    Description = "Stop Web Crawlers Update API to enable the update of Referer Spammer Lists",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "threenine.co.uk", Email ="support@threenine.co.uk", Url ="https://threenine.co.uk"}
                });
                var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "api.xml");
                 c.IncludeXmlComments(filePath);  
            }
          );
       }

View Full Code

Annotate Controller Methods

This is an important step when documenting your API. All your publicly accessible methods will require annotation in order for the documentation to generate. If you fail to annotate your public methods, this may result in an error page being generated, which to be honest can be quite confusing and cryptic.

Essentially what this error page attempts to tell you is that, Swagger detected some public methods, but wasn’t sure if they were API methods so just fell over in a heap.

We should annotate our public controller methods and while we’re at it add some additional XML Comments to provide further detail as to what our API delivers.

In this example I have just decorated the simple controller with some example documentation for illustrative purposes.

[Route("api/[controller]")]
    public class ValuesController : Controller
    {
        
        /// <summary>
        ///  Returns a collection of values
        /// </summary>
[HttpGet("[action]")] 
public IEnumerable Get() 
{ 
   return new string[] { "value1", "value2" }; 
} 
        
/// <summary>
///  Returns an item from a collection of values based on ID
/// </summary>
[HttpGet("[action] {id}")] 
public string Get(int id) 
{ 
  return "value"; 
}

When we review our swagger documentation we’ll now see our additional comments appear.

There may be occasion when you would like to provide further information as to the inner workings of the API. This can be achieved by using the additional Remarks
This content can be further enhanced with some additional text or even adding additional JSON or XML for further details.

/// <summary>
        ///  Returns a collection of values
        /// </summary>
        ///<remarks>
        /// This is a remark to add additional information about this method
        ///  GET /get
        /// {
        ///    "value1", 
        ///    "value2"
        /// }
        ///</remarks>
        [HttpGet("[action]")]
        public IEnumerable<string> Get()
        {
            return new string[] { "value1", "value2" };
        }

This information will now be displayed as follows

Summary

Swagger is a great tool to document and test your RESTFul APIs. Taking the time to integrate, provides benefits to you and your team by creating a simple UI to list all your APIs actions and provide details about the request and response object for each API action.

Integration with ASP.NET Core 2.0 is straight forward and requires minimal efforts. Swagger also offers various customization to suit your needs. In a future post i will provide details how to customise the swagger UI to implement your branding etc.

About
Latest Posts

Gary Woodfine

Technical Director at Denizon

Gary is Technical Director at Denizon, an independent software vendor specialising in IoT, Field Service and associated managed services,enabling customers to be efficient, productive, secure and scalable in a way which helps them address and reduce their ecological impact.

Denizon's product line successfully integrate IoT, Artificial Intelligence and Blockchain technology to enable efficient, productive, secure and scalable solutions to help organisations address increasing energy demands, ecological impact and Health & Safety concerns of their staff.

Latest posts by Gary Woodfine (see all)

Book Review : Digital Marketing for Dummies - October 17, 2019
Product Review : Lavolta Laptop Stand - October 17, 2019
Calling GraphQL API with Vue.JS - October 14, 2019

Documenting DotNet core API’s with swagger

Swagger

Swashbuckle.AspNetCore

Customization

Add Developer Details

Include XML Comment Descriptions

Annotate Controller Methods

Summary

Gary Woodfine

Latest posts by Gary Woodfine (see all)

Share this: