Introduction

API’s play a very important role in how our application will run and documenting the API’s in a format that everyone in the organization can understand as what is happening in the application. We will discuss one of the most used API documenting specifications called OpenAPI specifications. OpenAPI specification is a language agnostic format which is used to describe RESTful web services. The resulting files can be interpreted by applications to generate code, produce documentation and create virtual simulations of the services they describe. Let’s understand the OpenAPI specification with a example API document that describes the API service that allow us to retrieve list of users.

An OpenAPI document has three required sections:

What’s new in OpenAPI 3.0

1. Simplified structure with increased reusability
Open API Specification (OAS) 3.0 introduces a new, more simplified structure. The new structure is meant to make it easier to write and navigate OAS definitions — combining some of the existing objects from OAS 2.0, standardizing the naming used for different parts of the spec, and even introducing new objects to extend reusability within OAS 3.0.

2. Content negotiation support
OAS 3.0 introduced a number of changes to how the body of a request and a response can be defined. One significant change is that body and formdata parameters have been removed and replaced with request body.

3. Enhance security definitions
While the structure of the security definitions in OAS 3.0 remains consistent with OAS 2.0, there are some key changes that will impact how you describe security flows. One of the most noteworthy changes is that the OAuth 2 flows were renamed to match the OAuth 2 Specification.

4. Updated Parameter Type
As previously mentioned, OAS 3.0 removed two parameter types: body and formdata.OAS 3.0 also introduced a new parameter type, cookie, which was a requested update for documenting APIs that currently use cookies.

5. Support for Describing Callbacks
OAS 3.0 offers support for describing callbacks, which can be used to define asynchronous APIs or Webhooks. Callbacks let you handle requests that your service will send to some other service in response to certain events. This helps you improve the workflow your API offers to clients.