This repository has been archived by the owner on Jun 11, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
_apidoc.js
106 lines (99 loc) · 3.33 KB
/
_apidoc.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
// ------------------------------------------------------------------------------------------
// General apiDoc documentation blocks and old history blocks.
// ------------------------------------------------------------------------------------------
// ------------------------------------------------------------------------------------------
// Current Success.
// ------------------------------------------------------------------------------------------
// ------------------------------------------------------------------------------------------
// Current Errors.
// ------------------------------------------------------------------------------------------
/**
* @apiDefine CreateUserError
* @apiVersion 0.2.0
*
* @apiError NoAccessRight Only authenticated Admins can access the data.
* @apiError UserNameTooShort Minimum of 5 characters required.
*
* @apiErrorExample Response (example):
* HTTP/1.1 400 Bad Request
* {
* "error": "UserNameTooShort"
* }
*/
// ------------------------------------------------------------------------------------------
// Current Permissions.
// ------------------------------------------------------------------------------------------
/**
* @apiDefine admin Admin access rights needed.
* Optionally you can write here further Informations about the permission.
*
* An "apiDefinePermission"-block can have an "apiVersion", so you can attach the block to a specific version.
*
* @apiVersion 0.3.0
*/
// ------------------------------------------------------------------------------------------
// History.
// ------------------------------------------------------------------------------------------
/**
* @apiDefine admin This title is visible in version 0.1.0 and 0.2.0
* @apiVersion 0.1.0
*/
/**
* @api {get} /user/:id Read data of a User
* @apiVersion 0.2.0
* @apiName GetUser
* @apiGroup User
* @apiPermission admin
*
* @apiDescription Here you can describe the function.
* Multilines are possible.
*
* @apiParam {String} id The Users-ID.
*
* @apiExample {bash} Curl example
* curl -i https://api.example.com/user/4711
* @apiExample {js} Javascript example
* const client = AcmeCorpApi();
* const user = client.getUser(42);
* @apiExample {python} Python example
* client = AcmeCorpApi.Client()
* user = client.get_user(42)
*
* @apiSuccess {String} id The Users-ID.
* @apiSuccess {Date} name Fullname of the User.
*
* @apiError UserNotFound The <code>id</code> of the User was not found.
*/
/**
* @api {get} /user/:id Read data of a User
* @apiVersion 0.1.0
* @apiName GetUser
* @apiGroup User
* @apiPermission admin
*
* @apiDescription Here you can describe the function.
* Multilines are possible.
*
* @apiParam {String} id The Users-ID.
*
* @apiSuccess {String} id The Users-ID.
* @apiSuccess {Date} name Fullname of the User.
*
* @apiError UserNotFound The error description text in version 0.1.0.
*/
/**
* @api {post} /user Create a User
* @apiVersion 0.2.0
* @apiName PostUser
* @apiGroup User
* @apiPermission none
*
* @apiDescription In this case "apiErrorStructure" is defined and used.
* Define blocks with params that will be used in several functions, so you dont have to rewrite them.
*
* @apiBody {String} name Name of the User.
*
* @apiSuccess {String} id The Users-ID.
*
* @apiUse CreateUserError
*/