Documenting REST Services

Before a service provider can consume a service, they need a service contract. A service contract defines all the; details about a service:

• How can I call a service? What is the URI of the service?

• What should be the request format?

• What kind of response should I expect?

There are multiple options to define a service contract for RESTful services. The most popular one in the last couple of years is Swagger. Swagger is gaining a lot of ground, with support from major vendors in the last couple of years. In this section, we will generate Swagger documentation for our services.

The following quote from the Swagger website (http://swagger.io) defines the purpose of the Swagger specification:

Swagger specification creates the RESTful contract for your API, detailing all of its resources and operations in a human and machine readable format for easy development, discovery, and integration.

Generating a Swagger Specification

One of the interesting developments in the last few...