API Documentation With Swagger

Documentation is a set of documents provided on paper, or online, or on digital or analog media, for example, quick-reference guides. As a developer, it is very important to have reliable documentation about your work. It helps to jump into any development, maintenance and knowledge transfer of application. Most importantly, it is very helpful for other developers to understand programming code and application.

Application Programming Interface (API) is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact. Most of the applications today are the web application and powered by API. Therefore, it is very important that API needs to be well documented to be understood and consumed by another developer.

There are multiple tools to document API, here I am going to start with Open API Initiative-Swagger. Swagger is simple and easier to write and is easy to consume from developer to developer. I am not going to talk about all the features, pros and cons of swagger.

Now, let’s start API documentation with swagger in YAML. You can write your document in your favorite text editor or you can use swagger-editor.

If you are using text editor then create a file user.yml.

Firstly, we add generic information about our api.

# this is an example of the Users API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Sample API
  description: Users rest API
  version: "1.0.0"
# the domain of the service
host: api.sample.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /v1
produces:
  - application/json

Then we will add details about each API path which falls under paths: tag.

paths:
  /users:
    post:
      summary: Create User
      description: |
        Create a new user
      tags:
        - Users
      parameters:
        - name: body
          in: body
          schema:
            $ref: '#/definitions/CreateUserRequest'
      responses:
        201:
          description: Created
          schema:
            $ref: '#/definitions/UserResponse'

Here, I am creating create user API along with its request parameters and response.

Definitions are path templating and referenced by $ref tag. CreateUserRequest and UserResponse are defined under definitions section and their paths are referenced to request parameters and responses.

definitions:
  FirstName:
    type: string
    description: First name of user
    example: Raj
  LastName:
    type: string
    description: Last name of user
    example: Shrestha
  Age:
    type: integer
    minimum: 1
    maximum: 200
    example: 27
  Education:
    type: array
    items:
      type: object
      properties:
        level: 
          type: string
          description: Education level
        score:
          type: string
          description: Score
    example: [{level: 'Bachelor', score: '3.0'}]
  CreateUserRequest:
    type: object
    properties:
      first_name:
        $ref: '#/definitions/FirstName'
      last_name:
        $ref: '#/definitions/LastName'
      age:
        $ref: '#/definitions/Age'
      education:
        $ref: '#/definitions/Education'     
    required:
      - first_name
      - age
  UserResponse:
    type: object
    properties:
      first_name:
        $ref: '#/definitions/FirstName'
      last_name:
        $ref: '#/definitions/LastName'
      age:
        $ref: '#/definitions/Age'
      education:
        $ref: '#/definitions/Education'

In definitions, I have also made templates of users element which helps us to reduce repetitive work and update easily.

In the final document, we will put all together. You can also view this on gist. We have created a create user API. Similarly, we can build other APIs. In the beginning, it feels a little boring and time waste, but, after playing with the swagger documentation you will enjoy developing APIs.

In the next part, I will describe each part of the tags and UI for rendering swagger document. Stay Tuned.