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
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