OpenAPI is particular for describing and designingREST APIs. Written in YAML or JSON, OpenAPI gives a strategy for recording the endpoints, tasks, required/discretionary parameters, code tests, and practically anything you want to convey about your Programming API interface. These archives are effectively cleared by individuals and machines, rapidly altered, and, surprisingly, produced straightforwardly from the code base.

Previously known as Swagger, before being renamed the OpenAPI Specification(OAS) in 2016, OAS immediately became the predominant structure for portraying REST APIs. By mid-2017, OAS instruments surpassed 100,000+ downloads each day and have kept developing.

The specification is currently in its third iteration and the significant principal delivery since its transition to the OpenAPI initiative. So, what’s the big deal about the recent release if it has been so successful and effective?

Let’s discuss various new features of OpenAPI 3.0 in detail.

Leveraged in the case of staging & production servers

Previous version 2.0 permitted you to set a host, base URL and plans to apply across your Programming API interface documentation. With OAS 3.0, these fields are joined into a server’s property, gathering the report while offering help for various base URLs.

These can be characterized later in the archive to permit individual endpoints to have their unique base URL if necessary. It could be utilized on account of staging and production servers.

Despite how viable a device could be, it’s only worth a little because it is difficult to learn, digest, and get up and run. Considering this, OAS 3.0 highlights a few changes following gathering and improves the structure for readability and convenience.

We should look at the YAML report for OAS 2.0 and 3.0 to feature a portion of these comparisons. OAS 3.0 incorporates a few adjustments to the current parts object to accomplish this, with a specific spotlight on the reusability and consistency of the entire record.

OpenAPI Schema is now a valid JSON Schema.

The Schema object characterizes everything inside the ‘schema’ keyword in OpenAPI. It has forever been inexactly founded on JSON Schema and alluded to as a “subset superset” because it adds a few things and eliminates another thing from JSON Schema.

It has befuddled a few people in the OpenAPI people group. The two networks’ givers adjusted these details to determine the subset superset issue.

OpenAPI v3.0 depended on JSON Schema Draft 05, and JSON Schema has gone through a couple of drafts from that point forward, i.e., Draft 06, Draft 07, and Draft 2019–09. Regarding client input and tooling maintainers during the v3.1.0 released candidates, another little draft was delivered: Draft 2020–12.

It should be the final remaining one for some time. The JSON Schema group designs no significant changes, so if all works out positively, the last release is close to avoiding other disparities.

Structure Changes

So now a basic structure of an OAS3.0 file would look like as below;

openapi: 3.0.0
info: 
  version: '1.0.0'
  title: 'My Service APIs'
  description: 'API to demonstrate OAS3.0.'
paths: {}

Swap nullable for type arrays

By JSON Schema, the ‘type’ keyword can now characterize different sorts of a pattern with an array. It is helpful new usefulness however has additionally made nullable repetitive. To accomplish the objective of letting JSON Schema apparatuses comprehend OpenAPI, it was chosen to eliminate nullable instead of censuring it.

# OpenAPI v3.0
type: string
nullable: true

# OpenAPI v3.1
type:
- "string"
- "null"

This follows the keyword independence idea, where the keyword should add limitations; however, adding another keyword shouldn’t eliminate an imperative. Find and should settle this one rather rapidly.

Tweak exclusive Minimum and exclusive Maximum

These two keywords take a boolean value, which would modify the meaning of the `minimum` and `maximum` properties. In OpenAPI v3.1, they are denoted distinct values.

# OpenAPI v3.0
minimum: 7
exclusiveMinimum: true

# OpenAPI v3.1
exclusiveMinimum: 7

Use examples, not example.

OpenAPI has plenty of spots that can have an example or numerous examples. OpenAPI v3.0 can have ‘example’ or ‘examples’ at the Media Type level (demands, reactions, callbacks, and webhooks). It can likewise have a different sort of ‘example’ inside the Schema Object. This mapping object’s particular example was an OpenAPI-explicit keyword which is presently excessive now as JSON Pattern has ‘examples.’

Fundamentally, changing any ‘example’ inside a ‘schema’ to ‘examples’ and adding a dash toward the beginning (which is a YAML array). It is seriously composing if you’re writing YAML entirely by hand instead of utilizing a visual supervisor. Still, at the same time, it’s a component: it is currently significantly more straightforward to add various examples.

Previously, to get numerous examples for a property or schema, you would need to switch the model being utilized from a property guide to media-type examples, which felt like over-the-top excess.

Reusable Components

All parameters, responses, and definitions are presented under the nonexclusive component object. Definitions object is currently renamed to schemas. Note that a similar schema object can also be used in the request and response body.

openapi: 3.0.0
info:
 version: '1.0.0'
 title: 'My Service APIs'
 description: 'API to demonstrate OAS3.0'
paths: {}
components:
  Schemas:
     Employee:
       properties: {}

$schema is now allowed

The $schema keyword is discretionary; however helpful to characterize precisely the exact thing JSON Schema dialects a model is written in, which could be various drafts or even custom languages. Devices that help different dialects can handle the records somewhat unexpectedly, meaning you don’t necessarily have to change every one of your models while overhauling OpenAPI variants later.

OpenAPI is no doubt viable with JSON Schema since it is presently a JSON Schema dialect, so as a matter of course, any mapping is utilizing ‘$schema “https://spec.openapis.org/oas/3.1/dialect/base" dialects. If you split your patterns into other JSON/YAML documents and use $ref to highlight them, they could contain an alternate $schema and supersede this default.

{
   $schema: "http://json-schema.org/draft-07/schema#",
}

File Upload Payloads

In OpenAPI v3.0, depicting document transfers were signaled with a kind: string and the configuration set to byte, parallel, or base64. JSON Schema explains this with its contentEncoding and contentMediaType keyword, which are intended for precisely this kind of purpose.

Improved Reusability

The general design of the OAS 3.0 is enhanced for reusability. Host, BasePath, and Schemes are all moved to another idea called servers. Produces consumes, and ways are presently all in all called paths. Any remaining parts, similar to definitions, parameters, and reactions, are conventionally called components from now ahead.

Server Definition

Presently, ahead, you can characterize servers for your APIs. Assume you have three servers running, organizing, beta, and live. You can characterize those in your APIs, and your endpoints can be reported for every server.

openapi: 3.0.0
info:
 version: '1.0.0'
 title: 'My Service APIs'
 description: 'API to demonstrate OAS3.0'

New Headers Params

Help you define a parameter your API consumes based on HTTP Request Headers. Assist you with characterizing a boundary that your Programming API interface consumes because ofHTTP Request Headers.

name: limit
          in: header
          schema:
             type: integer
             minimum: 10
             maximum: 100
             example: 20

New Cookies Params

In session-based APIs, cookies are one of the important components. Hence, with OAS3.0, you can now define parameters depending on cookies.

Paths:
 /employees:
   get:
     parameters:
        - name: limit
          in: cookie
          schema:
             type: integer
             minimum: 10
             maximum: 100
             example: 20

New requestBody Option

While sending a POST demand, you don’t have to have a body boundary. It is supplanted with a request body. All things being equal, you can characterize the full request body as prior we represent for the reaction, in any event, for the different content types. The request body additionally permits sending structure information.

paths:
 /employees:
   post:
     requestBody:
        required: true
        content:
           application/JSON:
              schema: {}
           application/XML:
              schema: {}

Use of schema object for param

Presently characterizing any param expects the utilization of schema objects a great deal in each conceivable use case.

paths:
 /employees:
   get:
     parameters:
        - name: limit
          in: query
          schema:
             type: integer
             minimum: 10
             maximum: 100
             example: 20

Content is essential for APIs and has a few significant changes.

• Consumes and Produce eliminated

It can now be characterized individually, contingent upon request and response body media types.

• Various Media Types

It can be characterized in Request and Response bodies exclusively. Empowering your Programming API interface to help one response type for one endpoint and another response type for another endpoint.

Ranges in Responses

Instead of characterizing individual responses, you can now characterize range codes. You can characterize one response for all scopes of 200 and one more reaction for all scopes of 400. Upheld ranges are 1XX, 2XX, 3XX, and 4XX.

Support for describing callbacks

It’s a new element in OAS3.0. If you want to characterize a Programming API interface endpoint that will call a URL on consummation of the request, that can be described now.

With every one of the new highlights and adaptability of OpenAPI 3.0, documentation developers can affect the plan, development, and, at last, the progress of their APIs. We will see the latest features in OpenAPI 3.0 in the upcoming years. Follow us and learn about any changes that occur in Open API 3.0.

Please comment below or contact us for any queries, questions, or suggestions. Thanks!

Build APIs with reusable components — just like Lego!

Bit’s open-source tool help 250,000+ devs to build apps with components.

Turn any UI, feature, or page into a reusable component — and share it across your applications. It’s easier to collaborate and build faster.

→ Learn more

Split apps into components to make app development easier, and enjoy the best experience for the workflows you want:

→ Micro-Frontends

→ Design System

→ Code-Sharing and reuse

→ Monorepo