Let's assume you want to document the query parameters size and offset for your GET endpoint [→] thus https://example.com/api/v1/data?size=2&offset=8.
You will first need to declare the parameters: key, under which you will begin to list out all the needed query parameters.
The concatenated specification below shows a sample definition of the size and offset query parameters (lines: 12 to 27).
01: ...
02: paths:
03: /data:
04: get:
05: tags:
06: - v1
07: summary: Return all data
08: description: Describe this a bit more here
09: operationId: allData
10: description: Describe this a bit more here
11: operationId: allData
12: parameters:
13: - name: size
14: in: query
15: description: Set the number of records to fetch
16: required: false
17: schema:
18: type: string
19: default: 20
20: example: 2
21: - name: offset
22: in: query
23: description: number of records to skip before fetching
24: required: false
25: schema:
26: type: string
27: example: 8
28: ...Complete OpenAPI Spec
Find the complete snippet below. You can copy-paste this into the Swagger editor [↗] to see what it looks like when rendered.
Click to view complete OpenAPI Spec
01:
02: openapi: 3.0.3
03: info:
04: title: Simple OpenAPI template
05: description: |
06: Simple open API template
07: license:
08: name: Apache 2.0
09: url: http://www.apache.org/licenses/LICENSE-2.0.html
10: version: 1.0.11
11: servers:
12: - url: https://example.com/api/v1
13: tags:
14: - name: v1
15: description: Simple API (v1)
16:
17: paths:
18: /data:
19: get:
20: tags:
21: - v1
22: summary: Return all data
23: description: Describe this a bit more here
24: operationId: allData
25: parameters:
26: - name: size
27: in: query
28: description: Set number of records to fetch
29: required: false
30: schema:
31: type: string
32: default: 20
33: example: 2
34: - name: offset
35: in: query
36: description: number of records to skip before fetching
37: required: false
38: schema:
39: type: string
40: example: 8
41: responses:
42: '200':
43: description: successful operation
44: content:
45: application/json:
46: schema:
47: type: array
48: items:
49: $ref: '#/components/schemas/ResponseStructure'
50: '400':
51: description: Invalid status value
52:
53: components:
54: schemas:
55: ResponseStructure:
56: type: object
57: properties:
58: name:
59: type: string
60: example: "John Doe"
61: age:
62: type: integer
63: example: 24
64: status:
65: type: boolean
66: salutation:
67: type: string
68: enum:
69: - Mrs
70: - Mr
72: - MissHere is another article you might like 😊 What Is An API Endpoint?