Blog Detail

Covid-19 Tracker Ask Question

preview image Information Technology
by Anurag Srivastava, May 9, 2020, 6:58:33 AM | 5 minutes |

Introduction to OpenAPI Specification

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.


Comments (0)

Leave a comment

Related Blogs

Geo distance search using Elasticsearch

May 16, 2020, 8:16:33 PM | Anurag Srivastava

Creating dynamic presentations using Kibana Canvas

Apr 10, 2020, 3:01:55 PM | Anurag Srivastava

Secure your Elastic Stack

Nov 4, 2019, 7:06:01 PM | Anurag Srivastava

Elasticsearch Installation and Configuration on Ubuntu 14.04

May 7, 2018, 11:55:02 AM | Lovish Sharma

Top Blogs

Secure your Elastic Stack

Nov 4, 2019, 7:06:01 PM | Anurag Srivastava

Creating dynamic presentations using Kibana Canvas

Apr 10, 2020, 3:01:55 PM | Anurag Srivastava

Elasticsearch Installation and Configuration on Ubuntu 14.04

May 7, 2018, 11:55:02 AM | Lovish Sharma

Introduction to OpenAPI Specification

May 9, 2020, 6:58:33 AM | Anurag Srivastava

Geo distance search using Elasticsearch

May 16, 2020, 8:16:33 PM | Anurag Srivastava