Initially, it was named as swagger specification, but later it was renamed as Open API specification. The Open API specification is a specification where the specification is a set of rules that specifies how to do something. Therefore, Open API specification is a set of rules that describes how to specify our Restful APIs in a language.
Irrespective of the technology that the api use, such as JAVA, PHP, .NET, or something else, we want our API to be easily consumed by the other developers that they are building.
In order to understand the API properly, we should know all the following about the API: What are the available endpoints like /customers, /employees, /orders, etc., available operation at each endpoint like GET, PUT, POST, DELETE, etc. what operations are available at each endpoint exposed by our API?
What parameters to pass and their data types? What will be API return and its data type, authentication methods to use? We want our external world or even our internal clients should know about our API without necessarily sharing the source code.
So, there must be some set of rules and standards that we should follow to describe the API, and everyone will follow the same set of rules and describe their api in the same way.
Here, Open Api Specification plays a role that simply defines a set of rules that specifies how to describe a Restful APIs. They have rules that describes every aspect of the Restful service. There are certain rules that specify the available endpoints at API.
Similarly, there are rules that specify the operation at each endpoint, basically there are rules for everything for example, for their parameters, for their data types, return values, authentication methods, etc. The open API specification can also be defined as a standard and language agnostic way to describe a Restful API.
The idea is to create a document following these rules either in a JSON or YAML format that describes your entire API such as available endpoints, available operations, what parameters to pass, return value, their data types, and authentication methods.
Let's see how to build an OAS file.
We will consider an example and then build a file. Suppose the company name is javatpoint.com, and the API service is uploading and sharing photos. Here, the API base URL is https://api.javatpoint.com/photo
The following is the example that how to start a file.
Swagger : '2.0'
# This is the document metadata
info:
version: "0.0.1"
title: Photo Service
host : api.javatpoint.com
basepath : /photo
schemes :
-https
In the above code, Open API specification calls swagger: 2.0 before writing the Open API specification.
The next step is to write about the file itself which is done with a key 'info:'. Under info, we have a version of string and title of API.
After title, the host of the API is api.javatpoint.com, basepath is /photo because the url is api.javatpoint.com/photo. The list of schemes which in this case only has schemes.