Because APIs are very common, the Open API Specification is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.
The OpenAPI Specification (OAS), formerly called the Swagger Specification, is an API description format for REST APIs. An Open API file allows you to describe your entire API, including the following:
- Available endpoints
- Endpoint operations (GET, PUT, DELETE, and so on)
- Parameter input and output for each operation
- Authentication methods
- Contact information, license, terms of use, and other information.
Open API has many versions and is rapidly developing. The current stable version is 3.0.
There are two formats, JSON and YAML, that are supported by OAS. Swagger and Open API both are different. Swagger has many products, including the following:
- Swagger UI (for validating Open API files and interactive docs)
- Swagger Codegen (for generating server stubs)
Whenever we develop a REST API, it is a better practice to create an Open API/Swagger file that captures all the necessary details and descriptions of the API. The file can then be used in Swagger UI to create interactive documentation.