1swagger: "2.0"
2info:
3 description: >-
4 REST API for the User Management Service
5 version: "1"
6 title: "User Management"
7 termsOfService: "Experimental, no SLA"
8 contact:
9 email: "development@bbgo.org"
10 license:
11 name: "Apache 2.0"
12 url: "http://www.apache.org/licenses/LICENSE-2.0.html"
13# host: "localhost"
14basePath: "/user-service/v1"
15tags:
16- name: User
17 description: "User"
18
19- name: Token
20 description: "Token"
21
22schemes:
23- "https"
24- "http"
25paths:
26 /users:
27 post:
28 tags:
29 - User
30 summary: "an operation to register a new user"
31 description: >-
32 Registers a new user
33 operationId: "registerUser"
34 consumes:
35 - "application/json"
36 produces:
37 - "application/json"
38 parameters:
39 - name: payload
40 in: body
41 description: >-
42 Data for the user to be registered
43 schema:
44 $ref: "./Data.yaml"
45 required: true
46 responses:
47 201:
48 description: Created
49 headers:
50 Location:
51 description: URI of the registered resource
52 type: string
53 #format: uri
54 ETag:
55 description: >-
56 Fingerprint of the created resource
57 type: string
58 schema:
59 $ref: "./User.yaml"
60 400:
61 $ref: "./responses.yaml#/400"
62 401:
63 $ref: "./responses.yaml#/401"
64 403:
65 $ref: "./responses.yaml#/403"
66 500:
67 $ref: "./responses.yaml#/500"
68
69 get:
70 tags:
71 - User
72 summary: Get all users
73 description: >-
74 Get all users
75 operationId: "getUsers"
76 produces:
77 - "application/json"
78 parameters:
79 - $ref: "./parameters.yaml#/filter"
80 - $ref: "./parameters.yaml#/top"
81 - $ref: "./parameters.yaml#/skip"
82 - $ref: "./parameters.yaml#/search"
83 responses:
84 200:
85 description: OK
86 schema:
87 $ref: "./Users.yaml"
88 400:
89 $ref: "./responses.yaml#/400"
90 401:
91 $ref: "./responses.yaml#/401"
92 403:
93 $ref: "./responses.yaml#/403"
94 404:
95 $ref: "./responses.yaml#/404"
96 500:
97 $ref: "./responses.yaml#/500"
98 security:
99 - tokenAuth: [ADMIN, USER]
100
101 /users/{id}:
102 get:
103 tags:
104 - User
105 summary: "Retrieve a user by ID"
106 description: >-
107 Returns user
108 operationId: "getUser"
109 produces:
110 - "application/json"
111 parameters:
112 - in: path
113 name: "id"
114 description: "User ID"
115 type: string
116 required: true
117 responses:
118 200:
119 description: OK
120 headers:
121 ETag:
122 description: >-
123 Fingerprint of the user object retrieved
124 type: string
125 schema:
126 $ref: "./User.yaml"
127 400:
128 $ref: "./responses.yaml#/400"
129 401:
130 $ref: "./responses.yaml#/401"
131 403:
132 $ref: "./responses.yaml#/403"
133 404:
134 $ref: "./responses.yaml#/404"
135 500:
136 $ref: "./responses.yaml#/500"
137 security:
138 - tokenAuth: [ADMIN, USER]
139
140 delete:
141 tags:
142 - User
143 summary: Deletes a user
144 description: >-
145 Deletes a user
146 operationId: deleteUser
147 parameters:
148 - name: id
149 in: path
150 description: ID of a user to delete
151 required: true
152 type: "string"
153 responses:
154 204:
155 $ref: "./responses.yaml#/204"
156 400:
157 $ref: "./responses.yaml#/400"
158 401:
159 $ref: "./responses.yaml#/401"
160 403:
161 $ref: "./responses.yaml#/403"
162 404:
163 $ref: "./responses.yaml#/404"
164 500:
165 $ref: "./responses.yaml#/500"
166 security:
167 - tokenAuth: [ADMIN, USER]
168
169 /users/{id}/data:
170 put:
171 tags:
172 - User
173 summary: Update an existing user data
174 description: >-
175 Updates data for an existing user
176 operationId: updateData
177 consumes:
178 - application/json
179 produces:
180 - application/json
181 parameters:
182 - in: path
183 name: id
184 description: ID of the user to update
185 type: string
186 required: true
187 - in: body
188 name: payload
189 description: User data to be updated
190 required: true
191 schema:
192 $ref: "./Data.yaml"
193 - $ref: "./parameters.yaml#/ifmatch"
194 responses:
195 200:
196 description: OK
197 headers:
198 ETag:
199 description: "Fingerprint of the user object updated"
200 type: string
201 schema:
202 $ref: "./User.yaml"
203 400:
204 $ref: "./responses.yaml#/400"
205 401:
206 $ref: "./responses.yaml#/401"
207 403:
208 $ref: "./responses.yaml#/403"
209 404:
210 $ref: "./responses.yaml#/404"
211 412:
212 $ref: "./responses.yaml#/412"
213 500:
214 $ref: "./responses.yaml#/500"
215 security:
216 - tokenAuth: [ADMIN, USER]
217
218 /users/{id}/roles:
219 put:
220 tags:
221 - User
222 summary: Update roles for an existing user
223 description: >-
224 Updates roles for an existing user
225 operationId: updateRoles
226 consumes:
227 - application/json
228 produces:
229 - application/json
230 parameters:
231 - in: path
232 name: id
233 description: ID of the user to update
234 type: string
235 required: true
236 - in: body
237 name: payload
238 description: User roles to be updated
239 required: true
240 schema:
241 $ref: "./Roles.yaml"
242 - $ref: "./parameters.yaml#/ifmatch"
243 responses:
244 200:
245 description: OK
246 headers:
247 ETag:
248 description: "Fingerprint of the user object updated"
249 type: string
250 schema:
251 $ref: "./User.yaml"
252 400:
253 $ref: "./responses.yaml#/400"
254 401:
255 $ref: "./responses.yaml#/401"
256 403:
257 $ref: "./responses.yaml#/403"
258 404:
259 $ref: "./responses.yaml#/404"
260 412:
261 $ref: "./responses.yaml#/412"
262 500:
263 $ref: "./responses.yaml#/500"
264 security:
265 - tokenAuth: [ADMIN, USER]
266
267 /token:
268 post:
269 tags:
270 - Token
271 summary: Issues a token for an authenticated user
272 description: >-
273 Issues a token for an authenticated user
274 operationId: issueToken
275 produces:
276 - application/json
277 responses:
278 200:
279 description: OK
280 schema:
281 $ref: "./AccessToken.yaml"
282 400:
283 $ref: "./responses.yaml#/400"
284 401:
285 $ref: "./responses.yaml#/401"
286 403:
287 $ref: "./responses.yaml#/403"
288 404:
289 $ref: "./responses.yaml#/404"
290 412:
291 $ref: "./responses.yaml#/412"
292 500:
293 $ref: "./responses.yaml#/500"
294 security:
295 - basicAuth: []
296
297securityDefinitions:
298 basicAuth:
299 type: basic
300 tokenAuth:
301 type: apiKey
302 in: header
303 name: AuthorizationView as plain text