EDDYMENS

Eddymens (List page)

Last updated 2023-03-20 05:22:27

Simple OpenAPI Starter Template

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

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