API documentation using Swagger?
If you want to interact with some service, you generally use an API (application program interface) which is a set of routines, protocols, and tools for building software applications. Basically, an API specifies how software components interact.
A REST API defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST etc…. Apart from long meetings with business stakeholders, choosing the right technology stack, and building an appropriate data-distribution model, there are a lot of finer details that can get overlooked.
A good API design makes the life of developer easy. It’s quick to understand with all the resources well organized, fun to interact with and easy on the eyes, so the people who consume your API have an easy and comfortable experience working with it. An API’s design is a solid blueprint on what your API wants to achieve and gives a comprehensive overview on all the endpoints and CRUD operations associated with each of them.
API design should have:
- The structure of resources
- The documentation of your resources
Why Swagger?
Here comes the use of Swagger in api documentation. Swagger is a documentation format written in either JSON or YAML where you can define an API. Swagger 2 is originally introduced by SmartBear Software and later they donated it to the Open API Initiative which now maintains this world standard API definition language. Swagger makes API design a breeze, with easy-to-use tools for developers, architects, and product owners.
Swagger is like a blueprint for a house, you wouldn’t start building a house until you had a blueprint nor would you want to start building an API before you had a blueprint for what it looks like so that’s what swagger is, it’s a set of rules to semantically describing an API. It consists of Swagger editor, Swagger codegen, Swagger UI. Lets dive into Swagger Editor for having a look at sample api documentation.
You can write Swagger definitions in YAML or JSON ,When you visit the swagger editor, the left hand side is where YAML code is written as you can see in this image and when you start to write your own code it gets converted automatically to an interface HTML and CSS that you can see one in the right hand side. From the YAML we can add the properties of the api’s like this is swagger 2.0 at the moment, so it is added as 2.0 in the swagger field and scheme, which are the transfer protocols used by the API. Swagger 2.0 supports both http and https. Then the domain name or the IP address of the host that serves the API under host field. This prefixes all the paths defined in the Swagger definition and this is relative for the host. This must be defined in the Swagger definition with a leading slash.
The above image shows a part of YAML file where the paths are listed. Here we can add and change each api properties. The path variable lists out all the endpoints like the one shown in the image under path, “/pet/{petId}” and each path lists the possible methods there exists for the endpoints like get, post, put etc… Under each methods we can add the parameters the method requires for successful working. There are several types of parameters and they have the following elements.
- name : name of the parameter
- type : type of the parameter(for primitive value parameters)
- schema : for request body
- description : a short description about the parameter
The parameter types are defined in Swagger according to the location of the parameter. This is defined in the element “in” under the “parameters” section. This can be either “query” or “path”. The “responses” section allows you to define the response format or type you expect from different APIs. This is defined under the “path” element and after the parameter definition(if any). You can also specify what is the response code you want as the response of the particular API. You can also add a brief description for the response. The “schema” keyword is used to define the response body.
We can specify the format of request and response whether JSON or XML. Whatever properties we add gets reflected on the right hand side of the design document. On scrolling down the YAML file, there is another field i.e the definitions which lists the models for both response bodies and request bodies of the APIs can be defined.Here there are 2 model objects shown as a sample, Order and Category which lists the possible fields coming under the objects. Let’s say, the response body of a defined API is directed to “Order” definition in the “definitions” section using “$ref” element under the “schema” keyword in the response filed as discussed in previous section, when defining the “Order” definition in the “definitions” section, we have to use the same name that used to point in the response section like the image shown below
Coming to the right hand side there is the api documentation area , on selecting the methods visible in the right hand side panel, it expands showing the properties we added via YAML and can test the api from there in all use case scenarios. The image shows the expanded for of the get method with path /pet/{petId}. There we can add the sample path in the textbox and click execute, which will shows the possible responses the api going to deliver.
At a point If we have a server setup in hand and is running with the api’s well developed, we can call the API from swagger editor by the test cases just like we use a postman for testing by giving all the necessary details like the endpoints, basepath, host, scheme etc.. in YAML file and call the api from the methods by giving the body and whatever items the api requires and the response will be shown in the response block.
An API can be your best friend but also your biggest liability. So it’s important to plan how it should be and define the implementation beforehand. This is to provide you the basic guides to write a simple and complete API definition using Swagger 2 API definition language.There are so many other things that can be included in a Swagger 2 API definition. You can refer to the swagger documentation and GitHub for the better understanding of the fields inside the YAML and how to use it in the proper way.