Document HTTP JSON APIs with the application/json content type

Endpoints in OpenAPI are defined underneath the paths key. Below is an example of defining a single endpoint:

openapi.yml
1paths:
2 /pets:
3 post:
4 summary: Create a new pet
5 description: Creates a new pet with the provided information
6 requestBody:
7 required: true
8 content:
9 application/json:
10 schema:
11 $ref: '#/components/schemas/Pet'
12 responses:
13 '200':
14 description: User created successfully
15 content:
16 application/json:
17 schema:
18 $ref: '#/components/schemas/Pet'

Examples

You can provide examples of requests and responses by using the examples key.

openapi.yml
1paths:
2 /pets:
3 post:
4 summary: Create a new pet
5 description: Creates a new pet with the provided information
6 requestBody:
7 required: true
8 content:
9 application/json:
10 schema:
11 $ref: '#/components/schemas/Pet'
12 examples:
13 PetExample:
14 summary: This is an example of a Pet
15 value:
16 name: Markley
17 id: 44
18 responses:
19 '200':
20 description: A Pet object
21 content:
22 application/json:
23 schema:
24 $ref: '#/components/schemas/Pet'
25 examples:
26 PetExample:
27 summary: This is an example of a Pet
28 value:
29 name: Markley
30 id: 44