The previous page showed how to define API endpoints but it didn’t explain how to describe the content of the responses through the
content field. This page clarifies this important field, which can also be used to describe queries, as shown in the Parameters page.
This allows returning content (or accepting content) in different formats, each one with a different structure described by the Media Type Object. Wildcards are accepted for the media types, with the more specific ones taking precedence over the generic ones.
content: application/json: ... text/html: ... text/*: ...
The structure is described in the
schema field explained next.
content: application/json: schema: ...
The Schema Object defines a data type which can be a primitive (integer, string, …), an array or an object depending on its
type is a string and its possible values are:
object. Depending on the selected type a number of other fields are available to further specify the data format.
For example, for
string types the length of the string can be limited with
integer types, accept
maximum values. No matter the type, if the amount of options for the data is limited to a certain set, it can be specified with the
enum array. All these properties are listed in the Schema Object specification.
Example integer with limited range:
content: application/json: schema: type: integer minimum: 1 maximum: 100
Example string with only three valid options:
content: application/json: schema: type: string enum: - Alice - Bob - Carl
Array types must have an
items field, which is a Schema Object itself, and defines the type for each element of the array. Additionally, the size of the array can be limited with
content: application/json: schema: type: array minItems: 1 maxItems: 10 items: type: integer
Finally, object types must have a
properties field listing the properties of the object. This field is a map pairing property names with a Schema Object defining their type. This allows building data types as complex as required.
Here’s an example defining an object with two fields: a
productName string and a
content: application/json: schema: type: object properties: productName: type: string productPrice: type: number
The Tic Tac Toe sample API given so far has one endpoint with one unspecified response. The snippet below adds the description of this content:
openapi: 3.1.0 info: title: Tic Tac Toe description: | This API allows writing down marks on a Tic Tac Toe board and requesting the state of the board or of individual squares. version: 1.0.0 paths: # Whole board operations /board: get: summary: Get the whole board description: Retrieves the current state of the board and the winner. responses: "200": description: "OK" content: application/json: schema: type: object properties: winner: type: string enum: [".", "X", "O"] description: | Winner of the game. `.` means nobody has won yet. board: type: array maxItems: 3 minItems: 3 items: type: array maxItems: 3 minItems: 3 items: type: string enum: [".", "X", "O"] description: | Possible values for a board square. `.` means empty square. ...
The response contains an object is JSON format with two fields:
winneris a string with only three possible values:
boardis a 3-element array where each item is another 3-element array, effectively building a 3x3 square matrix. Each element in the matrix is a string with only three possible values:
This document is starting to grow too big and complex. The Reusing Descriptions page explains how to name sections of an OpenAPI document in order to reuse them (like the strings with three options above, which appear twice).
This page has shown how to describe the content of the body of a response or query. More precisely:
contentfield maps Media Types to Media Type Objects.
- Each Media Type Object has a
schemafield describing a Schema Object.
- Schema Objects define a data
typewhich can be customized through multiple properties like
propertiesand many more.
The next page explains how to define the parameters that an endpoint accepts.