1
+ # OpenAPI version identifier - required for OpenAPI 3.0 domains
2
+ openapi : 3.0.0
3
+
4
+ # ######################
5
+ # Optional info section
6
+ # ######################
7
+ info :
8
+ title : Acme Components
9
+ description : Common components for Acme REST APIs
10
+ version : ' 1.0.0'
11
+
12
+ components :
13
+
14
+ # ###################
15
+ # Common data models
16
+ # ###################
17
+ schemas :
18
+ ErrorModel :
19
+ type : object
20
+ required :
21
+ - code
22
+ - message
23
+ properties :
24
+ code :
25
+ type : integer
26
+ format : int32
27
+ message :
28
+ type : string
29
+
30
+ # ###################
31
+ # Common parameters
32
+ # ###################
33
+ parameters :
34
+ offsetParam :
35
+ name : offset
36
+ in : query
37
+ schema :
38
+ type : integer
39
+ minimum : 0
40
+ description : The number of items to skip before returning the results
41
+ limitParam :
42
+ in : query
43
+ name : limit
44
+ schema :
45
+ type : integer
46
+ format : int32
47
+ minimum : 1
48
+ maximum : 100
49
+ default : 20
50
+ description : The number of items to return
51
+
52
+ # ######################
53
+ # Common request bodies
54
+ # ######################
55
+ requestBodies :
56
+ NewItem :
57
+ description : A JSON object containing item data
58
+ required : true
59
+ content :
60
+ application/json :
61
+ schema :
62
+ type : object
63
+
64
+ # ###################
65
+ # Common responses
66
+ # ###################
67
+ responses :
68
+ GeneralError :
69
+ description : An error occurred
70
+ content :
71
+ application/json :
72
+ schema :
73
+ $ref : ' #/components/schemas/ErrorModel'
74
+ headers :
75
+ X-RateLimit-Limit :
76
+ $ref : ' #/components/headers/X-RateLimit-Limit'
77
+ X-RateLimit-Remaining :
78
+ $ref : ' #/components/headers/X-RateLimit-Remaining'
79
+
80
+ # ########################
81
+ # Common headers
82
+ # (except request headers - they are defined as parameters)
83
+ # ########################
84
+ headers :
85
+ X-RateLimit-Limit :
86
+ description : Request limit per hour
87
+ schema :
88
+ type : integer
89
+ example : 100
90
+ X-RateLimit-Remaining :
91
+ description : Remaining requests for the hour
92
+ schema :
93
+ type : integer
94
+ example : 94
95
+
96
+ # ######################
97
+ # Common path items
98
+ # ######################
99
+ pathitems :
100
+ EntityOperations :
101
+ get :
102
+ summary : Get all items
103
+ description : This operation supports pagination
104
+ parameters :
105
+ - $ref : ' #/components/parameters/offsetParam'
106
+ - $ref : ' #/components/parameters/limitParam'
107
+ responses :
108
+ ' 200 ' :
109
+ description : A list of items
110
+ default :
111
+ $ref : ' #/components/responses/GeneralError'
112
+ post :
113
+ summary : Add a new item
114
+ requestBody :
115
+ $ref : ' #/components/requestBodies/NewItem'
116
+ responses :
117
+ ' 201 ' :
118
+ description : Created
119
+
120
+ # #####################################
121
+ # Common examples of input/output data
122
+ # #####################################
123
+ examples :
124
+ tshirt :
125
+ summary : Sample T-shirt data
126
+ value :
127
+ # Example value starts here
128
+ id : 17
129
+ name : T-shirt
130
+ description : 100% cotton shirt
131
+ categories : [clothes]
132
+
133
+ # ########################
134
+ # Common link definitions
135
+ # See: https://swagger.io/docs/specification/links/
136
+ # ########################
137
+ links : {}
138
+
139
+ # ########################
140
+ # Common callback definitions
141
+ # See: https://swagger.io/docs/specification/callbacks/
142
+ # ########################
143
+ callbacks : {}
0 commit comments