The certain kind of requests require extra data such as POST, PUT method, and these methods are known as HTTP methods.
The body that includes these methods known as request body. The data included in a request body can be formatted either in a JSON or XML format.
All the responses represented in a response body can be formatted in a JSON format. Here, schema mainly defines the structure of the data.
The OAS schema object is based off the JSON Schema Specification.
Schema of the data determines what are the keys in the key/value pairs, what type of data are the values. There can be many levels in a schema.
$ref :-
The $ref is a special OAS key that indicates that the value is a reference to a structure somewhere else in the YAML file. It is useful so that we do not have so many indentation levels in the YAML file.
Let's understand through an example.
File1:
in: body
required: true
schema:
$ref: '#/definitions/newAlbum'
File2:
newAlbum
properties:
name:
type: string
In File1, we have defined a $ref key inside the schema having a value '#/definitions/newAlbum'. We have created one more file named as File2 where we have defined a new key named as 'definitions' which has one more key named as 'newAlbum', and the indentation structure is reflected in $ref key in File1.
Request body
The request body contains the parameters defined under the parameters key. The following is the list of parameters:
- name: It is just written for the reference but not shown in the documentation.
- in: It has 'in' key which is set to body.
- required: It is the key which is typically set to true.
- Schema: Instead of type, it has a schema key which has a key of $ref and $ref contains the value of reference path in quotes.
Example of Request body
# Query Parameters
parameters:
-name: album
in: body
required: true
schema:
$ref: '#/definitions/newAlbum'
The above YAML has a POST request that contains the parameters key. The parameters has a list with a name 'album'. It has a schema that contains $ref key with an intended path of a schema.
Schema Section
- In the schema section, we create a key called as definitions at the end of the file.
- Then, we add a level and give it a name from the $ref value.
- Add a properties key.
- For each top element in the JSON, add a key of its name.
- Add a type key that says what type of key it is.
- Add other keys for other data.
Example of Schema
newAlbum:
properties:
name:
type: string
date:
type: string
In the above schema, we can observe that newAlbum has two properties named as name and date, and both are of string type.
Note: The values of key/value don't have to be simple type; we can add other objects as values. To do this, we need to follow the steps which are given below:
- First, we need to use a type of object.
- Then, we need to add a new level with properties:, and then we continue as we did before
type: object
properties:
first name:
type: string
last name:
type: string
In the above schema, we can observe that schema is the type of object followed by the properties key. The properties key has two properties named as first name and last name of type string.
The above file has lots of indentation. To overcome this problem, we can use $ref from within your definition. Let's understand through an example.
$ref: '#/definitions/person'
person:
properties:
first name:
type: string
last name:
type: string
In the above case, author key has the $ref key that indicates to the path of the definition of the person key. The person has the properties key that has two properties named as first name and last name.
Schema array
- We can also add arrays.
- We use a type of array.
- Then, we add a key of items.
- And define the type and any other properties.
The syntax for declaring a schema array is:
type: array
items:
type: string
In the above example, marks is the array having items of type string.
Schema array with $ref
For the complex type, we use $ref for the array items. Let's understand through an example.
type: array
items:
$ref: '#/definitions/photo'
photo:
properties:
id:
type: integer
longitude:
type: number
latitude:
type: number
In the above schema, photos is the key of type array and has the list of items that are intended to the path of the photo key. The photo key has three properties, i.e., id of type integer, longitude of type number and latitude of type number.