Documenting .NET Web Services using OpenAPI (formally Swagger) and Swashbuckle

document-651712_640

Web services are increasingly common–driven by the rise of web and mobile apps, and application architecture philosophies such as microservices.

The current vogue is to create RESTful web services. These expose data as a set of resources (entities) and use the features of the HTTP protocol to operate on these resources.

The HTTP protocol contains a set of verbs, such as POST, GET, PUT and DELETE. These can be mapped to the standard CRUD (Create, Read, Update, Delete) operations often performed in a database-driven business application, with the resources being the records in the database tables. One of benefits of RESTful APIs is that they are lightweight and play nicely with existing web technologies and tools.

Groping around in the dark

I use a lot of third party web services in my consulting work. One of the biggest complaints I have with them, is the weakness of the documentation. And, when I say, “weakness,” I mean “complete absence.” I usually have to contact a developer at the organization that developed the API to find out how to use it. Problems include:

  • no, out of date or broken sample code
  • lack of clarity of the endpoints
  • no clear description of how to obtain authorization
  • incomplete enumeration of possible field values
  • inadequate documentation of query parameters
  • no information on response values and error conditions

Most of the time I’m left to explore the API to try and work out the details. RESTful services have made this easier by allowing browsing using browsers and the excellent Fiddler web debugging proxy, but it’s still a time consuming process–and many “RESTful” services don’t adhere to the rules.

Open API Initiative

Given the state of play in web services, I welcome the goal of the Open API Initiative, to define a standard language-agnostic interface to REST APIs, which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

Applications implementing the initiative’s OpenAPI Specification (formally known as Swagger) expose standardized JSON files that can be used to create automated dynamic documentation and client application code.

One of the informal benefits of implementing a standard specification is that it makes developers think more about the design of their web service APIs, which is a good thing in itself. And, it’s good for the vendors too. A better API attracts more users.

Swashbuckle

Of course, one of the reasons that web services are so poorly documented is that developers hate to do documentation—and it’s easier for them to talk management into spending less money by moving on once the code is done. So, there’s no way developers are going to spend time learning some complicated specification just because it helps other developers.

The good news is that you can implement the OpenAPI Specification in your ASP.NET Web API applications with hardly any effort at all. Swashbuckle provides a OpenAPI Specification generator and playground/exploration UI via a NuGet package.

Implementing the OpenAPI Specification in a Web API service using Swashbuckle

Let’s create a Web API service that looks up a UK address using a building number and post code. It has an AddressController with the following GET action

public Address Get(int number, string postCode)
{
    /* Call service that looks up address */

    return new Address { Number = number, Street = "Main Road", Town = "London", 
        PostCode = postCode, Country = "UK" };
}

Include Swashbuckle via the NuGet Package Manager Console

install-package Swashbuckle

This, amongst other things, creates a SwaggerConfig class in the App_Start folder. This contains single method (Register) with a comprehensive (and commmented) set of the configuration options. Most are disabled (commented out). To simplify things, strip this down to

public static void Register()
{
    GlobalConfiguration.Configuration.EnableSwagger(
        c =>
            {
                c.SingleApiVersion("v1", "Swashbuckle Demo");
            }).EnableSwaggerUi();
}

Run the application and browse to (change the port number, as required)

http://localhost:49784/swagger/

This displays the OpenAPI playground, showing the API details and tools for calling the API. As you can see, the UI details the required query parameters (number: integer and postCode: string) and the return value (JSON object and HTTP 200).

Swashbuckle API

Fill in the number and postCode parameters to Try it out!.

Swashbuckle playground

This shows us the details of the request and response.

Swashbuckle has a lot of additional power—if you want to use it. XML comments can be used to customize and extend the documentation produced. Also, authentication details can be specified and integrated into the playground.

So, a high quality API, playground and implementation of the OpenAPI Specification—all with almost no effort. Works for me and more importantly, let’s hope it works for the vendors of the next API I have to consume!

If you are interesting in learning more about build web services in .NET, Learning Tree has a number of courses that will help.

Type to search blog.learningtree.com

Do you mean "" ?

Sorry, no results were found for your query.

Please check your spelling and try your search again.