HTTP JSON Endpoints

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

1 paths:
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

1 paths:
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

1	paths:
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'