Web API documention using Swagger / Swashbuckle

I have recently been tasked in work with documenting an existing Web API.  This Web API used an older version of Swagger, which had been customised to get around the features that the version did not address at the time. My task was to update that version of Swagger to use the most recent version of Swashbuckle from nuget.  SwashBuckle is used to add Swagger to Web API projects.

The first step was to add Swagger via nuget.

Install-Package Swashbuckle.Core

The next step is to customise the Swagger configuration.  If you use OWIN like our API did, then the Swagger configuration would go into the Startup.cs class.  A basic configuration would look like this;

httpConfiguration
    .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API"))
    .EnableSwaggerUi();

So with the basic configuration out of way, how do you describe what your API actions do?

Go to the project properties – Build – Output.  There will be a checkbox for enabling the XML comments and then a path to an XML file will need to specified, something like “Project.xml”.

Then each API controller action would be decorated with the XML comments that should be familiar but if not:

/// <summary>This is a example</summary>
/// <param name=”example”>Description of example parameter</param>
/// <return>Example return description value</return>

So now to navigate to the Swagger URL.  It should no build the documentation based on the XML comments

https://<your-url>/swagger

The url doesn’t have to be the default.  This can be customised in the Swagger config and changed in “EnableSwaggerUi”

httpConfiguration
    .EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API"))
    .EnableSwaggerUi(“docs/ui/app/{*assetPath});

The assetPath parameter will add “index”.  The “index” page can also be customised but it is recommended that you use the template provided by the Swashbuckle site and then you can change the bits that you need to update.  Using a custom page can be achieved by altering Swagger UI section in the config and setting CustomAsset to point to your own “index” file where ever that is in your solution.

The configuration of Swagger is quite extensive and there isn’t a lot you can’t do. 

Issues

I was documenting an existing API and found out that it doesn’t really deal with inheritance (an action was on a base controller).  On doing a bit digging, I seen a few things that stated this was by design.

The other problem I had was with the response XML tags

/// <response code=”200”>Valid example request</response>

Adding the XML tags didn’t work for me, these comments were not added to the Swagger documentation.  I had to rely on Swagger Response data anotations to correctly document the response codes and what they meant in context of our application.

Use the “<remarks>” tag for the implementation notes.

Conclusion

In conclusion, I found Swagger easy to work and easy to configure.  There is plenty configuration options that I didn’t use and might suit your project.  The documentation is good and can only get better.  Swagger gives you a decent alternative to Word documents and keep it all together in one place.

As ever if anything is incorrect or inaccurate, please let me know.