API documentation with OpenAPI

Is it important to make an API documentation? YES

What is an API documentation?

It is a document which describes APIs. Simple is it? Let’s dive into what actually is this. API documentation holds each and every information about APIs of the system. It includes all the responses, requests, body information, security information and technically all the things which are embedded in APIs.

Is it needed to do this? Yes definitely.

Why this is important?

There are so much of benefits of creating an API documentation such as it saves time, increase awareness, saves money, decrease development time and so on.

When the API document is created it is easy for developers to develop their applications which leads to increase awareness about APIs. Then it will save time which leads to save money.

Let’s take an example where two companies developing web application using MEAN stack and one uses an API document and other don’t. Then the frontend and backend developers which having the API document they develop the application simultaneously (backend and frontend) and on other company which don’t have the API documentation, developers sometimes have to wait till backend developers complete their part which will increase the time of development and increases cost.

Let’s Start with OpenAPI

In openAPI we can use either yaml or json and for this tutorial yaml is used. Following is the basic structure for an API document

openapi: 3.0.0
info:
  version: <version>
  title: <title>
paths:
  <APIs>

Basic structure of an API is as follows

paths:
  /path:
    method:
      responses:
        <list_of_responses>

Let’s make some APIs which following the basic structure which having responses only. Responses are identify using the status code and it should have a description.

/students:
  get:
    description: This is to get students details
    responses:
      "200":
        description: Successfully get student details
        content:
          application/json:
          schema:
            type: string

Content is also defined in the response to give information about the response body. It includes the content type which may be application/json, application/xml, application/csv etc and it defined the structure of content in schema. For the above example it will return a application/json with string.

Types in OpenAPI

There are 6 types in OpenAPI which are array, boolean, integer, number, object, string.

• Array is consists of items as follows. Items can be one of above 6 types.

schema:
  type: array
  items:
    type: <type>

• Boolean, integer, number and string are atomic types.
• Object must have properties as follows.

schema:
  type: object
  properties:
    name:
      type: <type>
    age:
      type: <type>

Add a array or students to the response

Let’s add array of student objects which having name, age and height.

/students:
  get:
    description: This is to get students details
    responses:
      "200":
        description: Successfully get student details
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: integer
                  height:
                    type: number

Add multiple responses to the API

Then let’s add multiple responses to the API. It can be simply adding them after “200” response.

/students:
  get:     
    description: This is to get students details
    responses:
      "200":
        description: Successfully get student details
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: integer
                  height:
                    type: number
      "401":
        description: Authorization failure(Unauthorised)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      "404":
        description: Request not found(Not Found)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string

Path and Query parameters

Path and query parameters are heavily used in APIs. These parameters are added in the parameters section in the API as follows.

/path:
  parameters:
    <add_parameters_here>
  responses:
    <responses>

Path parameters

Path parameters can be defined as follows which should have name, in, required and schema.

name: <name_of_path_paramater>
in: path
required: <is_required>
schema:
  type: <type>

Query parameters

Query parameters are also follow the same structure as path parameters.

name: <name_of_query_paramater>
in: path
required: <is_required>
schema:
  type: <type>

Let’s get details about a specific student which can be query using the age.

/students/{student-id}:
  get:
    description: This is to get a specific student detail
    parameters: 
      - in: path
        name: student-id
        required: true
        schema:
          type: string
      - in: query
        name: age
        required: false
        schema:
          type: string
    responses:
      "200":
        description: Successfully get studen detail
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                age:
                  type: integer
                height:
                  type: number
      "401":
        description: Authorization failure(Unauthorized)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      "404":
        description: Request not found(Not Found)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string

Add a request body to post request

Hurray! This is the final part of this tutorial. It is adding a request body to an API. Let’s create a post method to “/students” API

/students:
  get:     
    description: This is to get student details
    responses:
      "200":
        description: Successfully get student details
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: integer
                  height:
                    type: number
      "401":
        description: Authorization failure(Unauthorised)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      "404":
        description: Request not found(Not Found)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
  post:
    description: This is to get create a student
    requestBody:
      required: true
      content:
        application/json:
          schema: 
            type: object
            properties:
              name:
                type: string
              age:
                type: integer
              height:
                type: number
    responses:
      "201":
        description: Created application(Created)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      "401":
        description: Authorization failure(Unauthorized)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      "404":
        description: Request not found(Not Found)
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string

This is a basic introduction to OpenAPI documentation and there are so much things in OpenAPI. Hope you get basic understanding about how to create an API documentation and the value of it. 😊😊

If you have found this helpful please hit that 👏 and share it on social media :)