In this blog, we are going to cover what is Open API Specification (OAS), why we should use it, and how to create an Open API Specification (OAS) document. It is very important to understand why the API documentation is important before doing the actual development. So let us start with what is Open API Specification (OAS).

What is Open API Specification:
The Open API Specification (OAS) is a way using which we can document the API without writing the actual API code. It is an open-source format using which we can describe the APIs. In this process, we can either use the JSON or YAML format.  

These days the Open API specification is becoming a de-facto standard for describing the RESTful APIs. The Open API Specification is not dependent on any programming language and we can easily create the API documentation without implementing the actual logic. Using the OpenAPI we can define the available API endpoints, the method of APIs like GET or POST, The input and output parameters, authentication methods, contact information, and other details, etc.

Why we should use Open API Specification:
Now to question comes that why we should use the Open API Specification. It may look like an overhead because you may be thinking that once the requirement is over then instead of actual development why we should invest time on Open API Specification?

The answer is that it is written in JSON or YAML so it is not required to have any programming knowledge and anyone can define the documentation. Once the documentation is done, a human or machine can use that document to understand the API structure like the API endpoint, method, parameter it takes and the response it gives back. It fills the gap between the team members and works as a contract where the structure is defined at an early stage and developers can fill the logic to achieve the functionality. This contract is well suited especially for a microservice-based architecture where the API documentation can be used for the backend as well as the frontend team by removing any inter-team dependency.

How we can create the Open API Specification:
Now let us see how we can create the Open API Specification. Just take a very simple example to create APIs for user creation and listing. I am going to use the Visual Studio Code for the Open API document creation also I will follow the OpenAPI 3.0 version which is the latest one as of now. So to create the OAS document we need to do the following:

• Open the Visual Studio Code IDE and create a new file as api.yaml
  
  
• We need to install the "OpeAPI(Swagger) Editor and swagger viewer extension of the VS Code. These extension helps us to write the Open API documents and to preview it in the VS Code right pane.
  
  
• Now we can write the API document code in YAML format, if you want to write in JSON format then you can do that I prefer the YAML format because it provides more human readability rather than the JSON format.
  
  
• We need to start with the open API version, title, and URL, etc and after that, we can start the API endpoint description by providing the method name, summary, operationID, parameter we want to send, the response we are expecting from the API.
  
  
• We can also create the independent data object and can add the reference of those data objects in the API specification, like in the below example, we have created the UserObj and then used that reference in the API response specification.
  
  
• I have created the Open API specification document with the example to create a new user and list all users. Please refer to the below YAML code:
  
  

openapi: "3.0.0"
info:
  version: 1.0.0
  title: User API Documentation
servers:
  - url: https://example.com/v1
paths:
 
  # APIs for the Building management
  /users:
    post:
      summary: Creates the new user.
      operationId: createUsers
      parameters:
        - name: userName
          in: query
          description: The name of the user.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully returned a list of buildings
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/UserObj"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      summary: Returns the list of all user.
      operationId: listUsers
      responses:
        '200':
          description: Successfully returned a list of buildings
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/UserObj"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              
components:
 schemas: 
  # Building object schema is there to represent the fields and their data type for the buildings.
  UserObj:
    type: object
    properties:
      userId:
        type: string
        example: 101
      userName: 
        type: string
        example: Anurag Srivastava

 # If the request is not successful then we can use the error response instead of 200. It could be 500, or 400 errors.
  Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

• We can also see the preview of the API document by clicking "Ctrl+Shift+P" and then select "Preview Swagger" option. This will open the right pane with the Swagger API preview of the YAML document. Please refer to the below screenshot:
  
  

This way we can create the Open API Specification document and can use it for further development. It also supports code generation using which we can create the code structure in different languages or can create the client, etc. We can also use this document to create API using AWS API Gateway and Lambda services. I will also cover them in my future blogs. In case of any query please leave a comment.

Anurag Srivastava

Anurag Srivastava

Product Manager at Daikin R&D Center Hyderabad

• Daikin Airconditioning India Pvt. Ltd.
• Punjab Technical University

View profile