DotNetCore

Documenting DotNet core API’s with swagger




When developing an Api for your application it’s important to ensure you provide clear and concise information for developers who you intend to use your Api.

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.

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

The Project

The project we’ll use is one from my company, threenine.co.uk, and is an extension of our Free and Open Source WordPress plugin Stop Web Crawlers – an easy way to block referer spammers .

Can’t wait to see it in action ?

Check out the code on GitHub

Code

 

The intention is to develop an API to enabling the updating of Referer spam list for our 500+ user base. It is an experimental prototype at this stage.

Developing API for other developers and integrators 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.

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.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

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

We can now build and start our API again

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

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 VS Code we will need to add some additional lines to our .csproj file.

Essentially we are going to Create an XML file which will store our comments which will be stored in our bin folder.

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

 

 

We can annotate our controller with 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.

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.

 

This information will now be displayed as follows




Gary Woodfine

Freelance Full Stack Developer at threenine.co.uk
Helps businesses by improving their technical proficiencies and eliminating waste from the software development pipelines.

A unique background as business owner, marketing, software development and business development ensures that he can offer the optimum business consultancy services across a wide spectrum of business challenges.
  • Hi Gary,

    We’ve been struggling to get swagger to work properly. Any ideas perhaps why this is happening?

    https://uploads.disquscdn.com/images/f1fc5c9e81ca0fb7cbe5225a795813f91d098371167cace54162bb9eed677ef3.png

    • You’re basically getting a 500 Response. Without looking at your code, I would guess that your swagger.json file is not in the Directory expected along with XML file .

      Ensure you have the line
      var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, “SWCapi.xml”);
      c.IncludeXmlComments(filePath);
      and Check that the XML is being created

      • Thanks Gary, We will investigate further.

        • If you’re still stuck I am more than happy to arrange Skype, Slack or Google Hangouts to screen share and help trouble shoot

          • Vipul

            Hi Gary,
            I tried to setup the swagger configuration for our .netcore application which has few web api endpoints. Can you please guide me through this ? Error details below:
            500 : http://localhost:46702/swagger/v1/swagger.json
            Unable to Load SwaggerUI

            I would appreciate if you can arrange Skype or Google Hangouts for the same. Thank you for your valuable time.
            Thanks in advance.

          • Vipul,

            I would double check your folder structure. Ensure you have an XML in your application root directory. It can be an empty file to start with. In my case I have named my XML file SWCApi.xml .

            Check out the code on Github, as that is probably more complete than the code sample attached here.

          • Vipul,
            Appollogies my timetable currently just doesn’t enable me to offer skype calls at present, as I am working on clients premises

π