1	<?php
2
3	/**
4	* @apiDefine SuccessGet Response-Content
5	*
6	* @apiParam (GET) {String} page Page number of result.
7	*
8	* @apiSuccess (Response-Content)   {String}     current_page    page called.
9	* @apiSuccess (Response-Content)   {Array}      data            Array of asked data.
10	* @apiSuccess (Response-Content)   {String}     first_page_url  first page url.
11	* @apiSuccess (Response-Content)   {String}     next_page_url   next page url.
12	* @apiSuccess (Response-Content)   {String}     path            Base url.
13	* @apiSuccess (Response-Content)   {String}     prev_page_url   previous page url.
14	* @apiSuccess (Response-Content)   {Integer}    from            first entry index.
15	* @apiSuccess (Response-Content)   {Integer}    per_page        nb of entries by page.
16	* @apiSuccess (Response-Content)   {Integer}    to              last entry index.
17	*
18	*
19	*
20	* @apiSuccessExample Response-Content (example):
21	*     HTTP/1.1 200 OK
22	*     {
23	*
24	* @apiSuccessExample Response-Content (example):
25	*     HTTP/1.1 200 OK
26	*     {
27	*      "first_page_url": "http://xxxx/xxx?page=2",
28	*      "from": 16,
29	*      "last_page": 4,
30	*      "last_page_url": "http://xxxx/xxx?page=4",
31	*      "next_page_url": http://xxxx/xxx?page=3,
32	*      "path": "http://david-api-digital.advertise-me.net/api/latest/user/users",
33	*      "per_page": 15,
34	*      "prev_page_url": http://xxxx/xxx?page=1,
35	*      "to": 30,
36	*      "total": 60
37	*     }
38	*/
39
40	/**
41	* @apiDefine EntityError Error 422
42	*
43	* @apiError (Error 422) {json} Unprocessable Entity Something wrong with parameters.
44	*
45	* @apiErrorExample {json} 422:
46	*     HTTP/1.1 422 Unprocessable Entity
47	*     {
48	*       "error": "error description"
49	*     }
50	*/
51
52	/**
53	* @apiDefine UserId Request-Header
54	*
55	* @apiHeader (UserId) {Integer} X-Qwamplify-user-id User-id.
56	*
57	* @apiHeaderExample {json} Header (Example) :
58	*     {
59	*           "X-Qwamplify-user-id" : 1
60	*     }
61	*/
62
63	/******************** PERMISSIONS *********************/
64
65	/**
66	* @api {get} http://service_acls/api/permission 1.1 Permission - Get list
67	* @apiVersion 1.0.0
68	* @apiName GetAllPermission
69	* @apiGroup 1.Permission
70	* @apiDescription Get all Permissions.
71	* @apiPermission acls_view
72	*
73	* @apiUse UserId
74	* @apiUse SuccessGet
75	*
76	*/
77
78	/**
79	* @api {get} http://service_acls/api/permission/{id} 1.2 Permission - Get one
80	* @apiVersion 1.0.0
81	* @apiName GetOnePermission
82	* @apiGroup 1.Permission
83	* @apiDescription Get One Permissions.
84	* @apiPermission acls_view
85	*
86	* @apiUse UserId
87	*
88	* @apiSuccessExample Response-Data (example):
89	*     HTTP/1.1 200 Ok
90	*     {
91	*         id: 1,
92	*         name: permission,
93	*         description: permission description,
94	*         created_at: 2018-07-20 12:00:00,
95	*         updated_at: 2018-07-20 12:00:00,
96	*         roles: [...],
97	*         users: [...]
98	*     }
99	*
100	*/
101
102	/**
103	* @api {post} http://service_acls/api/permission 1.3 Permission - Store
104	* @apiVersion 1.0.0
105	* @apiName CreatePermission
106	* @apiGroup 1.Permission
107	* @apiDescription Create new Permission.
108	* @apiPermission acls_view && acls_edit
109	*
110	* @apiUse UserId
111	*
112	* @apiParam (POST) {String} name             permission's name.
113	* @apiParam (POST) {String} description      permission's decription.
114	* @apiParam (POST) {Array} [roles]      roles ids list to sync with permission.
115	* @apiParam (POST) {Array} [users]      users ids list to sync with permission.
116	*
117	*
118	* @apiSuccessExample Response-Data (example):
119	*     HTTP/1.1 201 Created
120	*     {
121	*         status: ok,
122	*         permission: 123
123	*     }
124	*
125	* @apiUse EntityError
126	*/
127
128	/**
129	* @api {put} http://service_acls/api/permission/{id} 1.4 Permission - Update
130	* @apiVersion 1.0.0
131	* @apiName UpdatePermission
132	* @apiGroup 1.Permission
133	* @apiDescription Update existing Permission.
134	* @apiPermission acls_view && acls_edit
135	*
136	* @apiUse UserId
137	*
138	* @apiParam (PUT) {String} [name]             permission's name.
139	* @apiParam (PUT) {String} [description]      permission's decription.
140	* @apiParam (PUT) {Array} [roles]             roles ids list to sync with permission.
141	* @apiParam (PUT) {Array} [users]             users ids list to sync with permission.
142	*
143	*
144	* @apiSuccessExample Response-Data (example):
145	*     HTTP/1.1 200 Ok
146	*     {
147	*         status: ok
148	*     }
149	*
150	* @apiUse EntityError
151	*/
152
153	/**
154	* @api {delete} http://service_acls/api/permission/{id} 1.5 Permission - Destroy
155	* @apiVersion 1.0.0
156	* @apiName DestroyPermission
157	* @apiGroup 1.Permission
158	* @apiDescription Remove existing Permission.
159	* @apiPermission acls_view && acls_edit
160	*
161	* @apiUse UserId
162	*
163	* @apiSuccessExample Response-Data (example):
164	*     HTTP/1.1 200 Ok
165	*     {
166	*         status: ok
167	*     }
168	*
169	* @apiUse EntityError
170	*/
171
172	/******************** ROLES *********************/
173
174	/**
175	* @api {get} http://service_acls/api/role 2.1 Role - Get list
176	* @apiVersion 1.0.0
177	* @apiName GetAllRole
178	* @apiGroup 2.Role
179	* @apiDescription Get all Roles.
180	* @apiPermission acls_view
181	*
182	* @apiUse UserId
183	*
184	* @apiUse SuccessGet
185	*
186	*/
187
188	/**
189	* @api {get} http://service_acls/api/role/{id} 2.2 Role - Get one
190	* @apiVersion 1.0.0
191	* @apiName GetOneRole
192	* @apiGroup 2.Role
193	* @apiDescription Get One Roles.
194	* @apiPermission acls_view
195	*
196	* @apiUse UserId
197	*
198	* @apiSuccessExample Response-Data (example):
199	*     HTTP/1.1 200 Ok
200	*     {
201	*         id: 1,
202	*         name: role,
203	*         description: role description,
204	*         group_id: 1,
205	*         created_at: 2018-07-20 12:00:00,
206	*         updated_at: 2018-07-20 12:00:00,
207	*         permissions: [...],
208	*         users: [...],
209	*         group: [...]
210	*     }
211	*
212	*/
213
214	/**
215	* @api {post} http://service_acls/api/role 2.3 Role - Store
216	* @apiVersion 1.0.0
217	* @apiName CreateRole
218	* @apiGroup 2.Role
219	* @apiDescription Create new Role.
220	* @apiPermission acls_view && acls_edit
221	*
222	* @apiUse UserId
223	*
224	* @apiParam (POST) {String} name             role's name.
225	* @apiParam (POST) {String} description      role's decription.
226	* @apiParam (POST) {Integer} group_id      group id.
227	* @apiParam (POST) {Array} [permissions]      permissions ids list to sync with role.
228	* @apiParam (POST) {Array} [users]      users ids list to sync with role.
229	*
230	*
231	* @apiSuccessExample Response-Data (example):
232	*     HTTP/1.1 201 Created
233	*     {
234	*         status: ok,
235	*         role: 123
236	*     }
237	*
238	* @apiUse EntityError
239	*/
240
241	/**
242	* @api {put} http://service_acls/api/role/{id} 2.4 Role - Update
243	* @apiVersion 1.0.0
244	* @apiName UpdateRole
245	* @apiGroup 2.Role
246	* @apiDescription Update existing Role.
247	* @apiPermission acls_view && acls_edit
248	*
249	* @apiUse UserId
250	*
251	* @apiParam (PUT) {String} [name]             role's name.
252	* @apiParam (PUT) {String} [description]      role's decription.
253	* @apiParam (PUT) {Integer} [group_id]      group id.
254	* @apiParam (PUT) {Array} [permissions]      permissions ids list to sync with role.
255	* @apiParam (PUT) {Array} [users]      users ids list to sync with role.
256	*
257	*
258	* @apiSuccessExample Response-Data (example):
259	*     HTTP/1.1 200 Ok
260	*     {
261	*         status: ok
262	*     }
263	*
264	* @apiUse EntityError
265	*/
266
267	/**
268	* @api {delete} http://service_acls/api/role/{id} 2.5 Role - Destroy
269	* @apiVersion 1.0.0
270	* @apiName DestroyRole
271	* @apiGroup 2.Role
272	* @apiDescription Remove existing Role.
273	* @apiPermission acls_view && acls_edit
274	*
275	* @apiUse UserId
276	*
277	* @apiSuccessExample Response-Data (example):
278	*     HTTP/1.1 200 Ok
279	*     {
280	*         status: ok
281	*     }
282	*
283	* @apiUse EntityError
284	*/
285
286	/******************** GROUP *********************/
287
288	/**
289	* @api {get} http://service_acls/api/group 3.1 Group - Get list
290	* @apiVersion 1.0.0
291	* @apiName GetAllGroup
292	* @apiGroup 3.Group
293	* @apiDescription Get all Groups.
294	* @apiPermission acls_view
295	*
296	* @apiUse UserId
297	*
298	* @apiUse SuccessGet
299	*
300	*/
301
302	/**
303	* @api {get} http://service_acls/api/group/{id} 3.2 Group - Get one
304	* @apiVersion 1.0.0
305	* @apiName GetOneGroup
306	* @apiGroup 3.Group
307	* @apiDescription Get One Groups.
308	* @apiPermission acls_view
309	*
310	* @apiUse UserId
311	*
312	* @apiSuccessExample Response-Data (example):
313	*     HTTP/1.1 200 Ok
314	*     {
315	*         id: 1,
316	*         name: group,
317	*         description: group description,
318	*         created_at: 2018-07-20 12:00:00,
319	*         updated_at: 2018-07-20 12:00:00,
320	*         roles: [...],
321	*         users: [...]
322	*     }
323	*
324	*/
325
326	/**
327	* @api {post} http://service_acls/api/group 3.3 Group - Store
328	* @apiVersion 1.0.0
329	* @apiName CreateGroup
330	* @apiGroup 3.Group
331	* @apiDescription Create new Group.
332	* @apiPermission acls_view && acls_edit
333	*
334	* @apiUse UserId
335	*
336	* @apiParam (POST) {String} name             group's name.
337	* @apiParam (POST) {String} description      group's decription.
338	* @apiParam (POST) {Array} [roles]      roles ids list to sync with group.
339	*
340	*
341	* @apiSuccessExample Response-Data (example):
342	*     HTTP/1.1 201 Created
343	*     {
344	*         status: ok,
345	*         group: 123
346	*     }
347	*
348	* @apiUse EntityError
349	*/
350
351	/**
352	* @api {put} http://service_acls/api/group/{id} 3.4 Group - Update
353	* @apiVersion 1.0.0
354	* @apiName UpdateGroup
355	* @apiGroup 3.Group
356	* @apiDescription Update existing Group.
357	* @apiPermission acls_view && acls_edit
358	*
359	* @apiUse UserId
360	*
361	* @apiParam (PUT) {String} [name]             group's name.
362	* @apiParam (PUT) {String} [description]      group's decription.
363	* @apiParam (PUT) {Array} [roles]             roles ids list to sync with group.
364	*
365	*
366	* @apiSuccessExample Response-Data (example):
367	*     HTTP/1.1 200 Ok
368	*     {
369	*         status: ok
370	*     }
371	*
372	* @apiUse EntityError
373	*/
374
375	/**
376	* @api {delete} http://service_acls/api/group/{id} 3.5 Group - Destroy
377	* @apiVersion 1.0.0
378	* @apiName DestroyGroup
379	* @apiGroup 3.Group
380	* @apiDescription Remove existing Group.
381	* @apiPermission acls_view && acls_edit
382	*
383	* @apiUse UserId
384	*
385	* @apiSuccessExample Response-Data (example):
386	*     HTTP/1.1 200 Ok
387	*     {
388	*         status: ok
389	*     }
390	*
391	* @apiUse EntityError
392	*/
393
394	/******************** USER *********************/
395
396	/**
397	* @api {get} http://service_acls/api/user/all/{type?} 4.1 User - Get All
398	* @apiVersion 1.0.0
399	* @apiName GetAllUsers
400	* @apiGroup 4.User
401	* @apiDescription Get all Users.
402	* @apiPermission acls_view
403	*
404	* @apiUse UserId
405	*
406	* @apiParam (GET) {String} [type]      role's decription.
407	*
408	* @apiSuccessExample Response-Data (example):
409	*     HTTP/1.1 200 Ok
410	*     {
411	*         current_page: 1,
412	*         data: [
413	*                  {
414	*                      id: 1,
415	*                      name: user,
416	*                      description: role description,
417	*                      created_at: 2018-07-20 12:00:00,
418	*                      updated_at: 2018-07-20 12:00:00,
419	*                      permissions: [...],
420	*                      roles: [...]
421	*                  }
422	*              ],
423	*          first_page_url: XXX?page=1,
424	*          from: X,
425	*          next_page_url: XXX?page=2,
426	*          path: XXX,
427	*          per_page: 15,
428	*          prev_page_url: null,
429	*          to: 2
430	*     }
431	*
432	*/
433
434	/**
435	* @api {get} http://service_acls/api/user/{id}/{type?} 4.1 User - Get one
436	* @apiVersion 1.0.0
437	* @apiName GetOneUser
438	* @apiGroup 4.User
439	* @apiDescription Get One User.
440	* @apiPermission acls_view
441	*
442	* @apiUse UserId
443	*
444	* @apiParam (GET) {Integer} id             user id.
445	* @apiParam (GET) {String} [type]      role's decription.
446	*
447	* @apiSuccessExample Response-Data (example):
448	*     HTTP/1.1 200 Ok
449	*     {
450	*         id: 1,
451	*         name: user,
452	*         description: role description,
453	*         created_at: 2018-07-20 12:00:00,
454	*         updated_at: 2018-07-20 12:00:00,
455	*         permissions: [...],
456	*         roles: [...]
457	*     }
458	*
459	*/
460
461	/**
462	* @api {put} http://service_acls/api/user/{id} 4.2 User - Update
463	* @apiVersion 1.0.0
464	* @apiName UpdateUser
465	* @apiGroup 4.User
466	* @apiDescription Update existing User's roles and permissions.
467	* @apiPermission acls_view && acls_edit
468	*
469	* @apiUse UserId
470	*
471	* @apiParam (PUT) {Array} [permissions]      permissions ids list to sync with user.
472	* @apiParam (PUT) {Array} [roles]      roles ids list to sync with user.
473	*
474	*
475	* @apiSuccessExample Response-Data (example):
476	*     HTTP/1.1 200 Ok
477	*     {
478	*         status: ok
479	*     }
480	*
481	* @apiUse EntityError
482	*/
483
484	/**
485	* @api {post} http://service_acls/api/user/{id}/can 4.3 User - HasPermission
486	* @apiVersion 1.0.0
487	* @apiName HasPermissionUser
488	* @apiGroup 4.User
489	* @apiDescription User has permission.
490	* @apiPermission acls_view
491	*
492	* @apiUse UserId
493	*
494	* @apiParam (POST) {Array} [permissions]      permissions ids list to control.
495	* @apiParam (POST) {bool} [all_needed]        users ids list to sync with role.
496	*
497	*
498	* @apiSuccessExample Response-Data (example):
499	*     HTTP/1.1 200 Ok
500	*     {
501	*         status: ok
502	*     }
503	*
504	* @apiUse EntityError
505	*/
506
507	/**
508	* @api {post} http://service_acls/api/user/{id}/is 4.4 User - HasRole
509	* @apiVersion 1.0.0
510	* @apiName HasRoleUser
511	* @apiGroup 4.User
512	* @apiDescription User has role.
513	* @apiPermission acls_view
514	*
515	* @apiUse UserId
516	*
517	* @apiParam (POST) {Array} [roles]      roles ids list to control.
518	* @apiParam (POST) {bool} [all_needed]        users ids list to sync with role.
519	*
520	*
521	* @apiSuccessExample Response-Data (example):
522	*     HTTP/1.1 200 Ok
523	*     {
524	*         status: ok
525	*     }
526	*
527	* @apiUse EntityError
528	*/