If you ever tried modifying the default "Pet Store" API spec that comes with editor.swagger.io [↗] you will notice it has a lot of bells and whistles you likely don't need and it takes a bit of time to clear most it.
I have put together a simpler starter template that you can copy and use instead.
01: openapi: 3.0.3
02: info:
03: title: Simple OpenAPI template
04: description: |
05: Simple open API template
06: license:
07: name: Apache 2.0
08: url: http://www.apache.org/licenses/LICENSE-2.0.html
09: version: 1.0.11
10: servers:
11: - url: https://example.com/api/v1
12: tags:
13: - name: v1
14: description: Simple API (v1)
15:
16: paths:
17: /data:
18: get:
19: tags:
20: - v1
21: summary: Return all data
22: description: Describe this a bit more here
23: operationId: allData
24: responses:
25: '200':
26: description: successful operation
27: content:
28: application/json:
29: schema:
30: type: array
31: items:
32: $ref: '#/components/schemas/ResponseStructure'
33: '400':
34: description: Invalid status value
35: post:
36: tags:
37: - v1
38: summary: Add data
39: description: Further description for adding data
40: operationId: addData
41: requestBody:
42: description: Request Body structure required to add data
43: content:
44: application/json:
45: schema:
46: $ref: '#/components/schemas/RequestStructure'
47: required: true
48: responses:
49: '200':
50: description: Successful operation
51: content:
52: application/json:
53: schema:
54: $ref: '#/components/schemas/ResponseStructure'
55: '405':
56: description: Invalid input
57:
58: /data/{dataId}:
59: patch:
60: tags:
61: - v1
62: summary: Update data
63: description: Further description for adding data
64: operationId: updateData
65: parameters:
66: - name: dataId
67: in: path
68: description: ID of datum to update
69: required: true
70: schema:
71: type: integer
72: format: int64
73: requestBody:
74: description: Request Body structure required to update data
75: content:
76: application/json:
77: schema:
78: $ref: '#/components/schemas/RequestStructure'
79: required: true
80: responses:
81: '200':
82: description: Successful operation
83: content:
84: application/json:
85: schema:
86: $ref: '#/components/schemas/ResponseStructure'
87: '405':
88: description: Invalid input
89:
90: delete:
91: tags:
92: - v1
93: summary: Deletes a pet
94: description: delete a pet
95: operationId: deletePet
96: parameters:
97: - name: dataId
98: in: path
99: description: ID of datum to update
100: required: true
101: schema:
102: type: integer
103: format: int64
104: responses:
105: '400':
106: description: Invalid input
107: components:
108: schemas:
109: RequestStructure:
110: type: object
111: properties:
112: name:
113: type: string
114: example: "John Doe"
115: age:
116: type: integer
117: example: 24
118: status:
119: type: boolean
120: salutation:
121: type: string
122: enum:
123: - Mrs
124: - Mr
125: - Mrs
126: - Miss
127: ResponseStructure:
128: type: object
129: properties:
130: name:
131: type: string
132: example: "John Doe"
133: age:
134: type: integer
135: example: 24
136: status:
137: type: boolean
138: salutation:
139: type: string
140: enum:
141: - Mrs
142: - Mr
143: - Mrs
144: - MissThere is an up-to-date version stored as a Gist [↗] as well.
Here is another article you might like 😊 The difference between a JWT and a bearer token