Schemas are used for defining request and response bodies.
Certain kinds of requests have extra data. This happens when you use certain HTTP methods, such as POST and PUT. The extra data is called the request body.
Typically the data is formatted in JSON or sometimes XML, but it can actually be anything, like an image, a video, or a sound file. So that's for requests.
The schema indicates the structure of the data
The OAS schema object is based off the JSON schema specification which is at http://json-schema.org/
So you can look into if you want all the details about what you can put in a schema object.
The main things that the schema define are: what are the keys in the key/value pairs, and what type of data are the values?
$ref is a special OAS key that indicates that the value is a reference to a structure somewhere else in the YAML file.
Request body
To define the request body, we add a parameter so that's under the parameters key.
Just like other parameters, it will have a name. But the name is just for reference.
For example, it won't show up in the documentation. It has an "in" key which is set to "body" It has required, which is typically set to true for most requests for bodies.
And then instead of type it has a schema key.
The schema has a key of $ref indented to a new level and then the value is the reference path in quotes.
Here's an example for a POST request. The parameter is named album and it has an in value of body.
it has a required value of true and the schema has a $ref key indented with a path to the schema.
Schema section
To create a schema section, you start by creating a key called definitions at the end of the file.
Then you add a level and give it the name from the $ref value. From there you add a properties key.
Then for each top level element in the JSON, add a key. Add a type key that says what type of data it is and add other keys for other data.
The values of key/value pairs don't have to be simple types.
You can add other objects as values, too. To do this simply, use a type of object.
Then add a new level with properties and continue like you did before.
You can see in this example for the author key.
As you can imagine this can add a lot of indentation.
So you can use $ref from within your definition.
In this example, I've modified the value of the author key adding a $ref key with a path to a key called person.
Arrays can also have items of a more complex type.
In this case, use $ref for the array items
You can specify that certain elements are required or optional.
You use the required key for this.
It contains a list of all properties that are required.
Response body
If the response is an array instead of an object then add type: array.
allOf
You can use the allOf key to combine several objects into one.
Schemas are used for defining request and response bodies.
Certain kinds of requests have extra data. This happens when you use certain HTTP methods, such as POST and PUT. The extra data is called the request body.
Typically the data is formatted in JSON or sometimes XML, but it can actually be anything, like an image, a video, or a sound file. So that's for requests.
The schema indicates the structure of the data
The OAS schema object is based off the JSON schema specification which is at
http://json-schema.org/So you can look into if you want all the details about what you can put in a schema object.
The main things that the schema define are: what are the keys in the key/value pairs, and what type of data are the values?
$refis a special OAS key that indicates that the value is a reference to a structure somewhere else in the YAML file.Request body
To define the request body, we add a parameter so that's under the parameters key.
Just like other parameters, it will have a name. But the name is just for reference.
For example, it won't show up in the documentation. It has an "in" key which is set to "body" It has required, which is typically set to true for most requests for bodies. And then instead of type it has a schema key.
The schema has a key of
$refindented to a new level and then the value is the reference path in quotes.Here's an example for a POST request. The parameter is named album and it has an
invalue ofbody.it has a
requiredvalue of true and the schema has a$refkey indented with a path to the schema.Schema section
To create a schema section, you start by creating a key called
definitionsat the end of the file.Then you add a level and give it the name from the $ref value. From there you add a
propertieskey.Then for each top level element in the JSON, add a key. Add a type key that says what type of data it is and add other keys for other data.
The values of key/value pairs don't have to be simple types.
You can add other objects as values, too. To do this simply, use a type of object.
Then add a new level with properties and continue like you did before.
You can see in this example for the author key.
As you can imagine this can add a lot of indentation.
So you can use
$reffrom within your definition.In this example, I've modified the value of the author key adding a
$refkey with a path to a key called person.Arrays can also have items of a more complex type.
In this case, use $ref for the array items
You can specify that certain elements are required or optional.
You use the
requiredkey for this.It contains a list of all properties that are required.
Response body
If the response is an array instead of an object then add type: array.
allOf
You can use the
allOfkey to combine several objects into one.