OpenAPI
Description
OpenAPI, formerly known as Swagger, is an open-source specification for defining and documenting RESTful APIs. It provides a standard way to describe the structure of an API, including endpoints, request/response formats, authentication methods, error handling, and more. Originally developed by SmartBear Software, the OpenAPI Specification (OAS) has become a widely adopted industry standard supported by a large community of developers and organizations.
Before we start any development, we need to have the endpoint neatly defined in specification and should have answer to below questions such as:
What should it receive as a request body, or what path parameters or query parameters are needed?
What would the response body look like?
What are the possible exceptions that would be returned?
This shows that design should be first defined and ready before any kind of development. Once we have specification, the Swagger Codegen can be used to produce a server stub for the defined API, and all that remains is to implement the service logic, tests, and our API is ready for the deployment and consumed by other parties.
An OpenAPI definition can be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and has many other use cases.
Latest Version
The latest version of the OpenAPI Specification is 3.1.0, as of 2024. Refer to below page for more details.
OpenAPI Specification Details
Best Practices
Sample YAML OpenAPI Specification File
Generating Code from an API Specification
Last updated
