forked from apidoc/apidoc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
example.js
209 lines (201 loc) · 7.5 KB
/
example.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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
/**
* @apiDefine admin:computer User access only
* This optional description belong to to the group admin.
*/
/**
* @api {get} /user/:region/:id/:opt Read data of a User
* @apiVersion 0.3.0
* @apiName GetUser
* @apiGroup User
* @apiPermission admin:computer
*
* @apiDescription Compare version 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
*
* @apiHeader {String} Authorization The token can be generated from your user profile.
* @apiHeader {String} X-Apidoc-Cool-Factor=big Some other header with a default value.
* @apiHeaderExample {Header} Header-Example
* "Authorization: token 5f048fe"
* @apiParam {Number} id User unique ID
* @apiParam {String} region=fr-par User region
* @apiParam {String} [opt] An optional param
*
* @apiExample {bash} Curl example
* curl -H "Authorization: token 5f048fe" -i https://api.example.com/user/fr-par/4711
* curl -H "Authorization: token 5f048fe" -H "X-Apidoc-Cool-Factor: superbig" -i https://api.example.com/user/de-ber/1337/yep
* @apiExample {js} Javascript example
* const client = AcmeCorpApi('5f048fe');
* const user = client.getUser(42);
* @apiExample {python} Python example
* client = AcmeCorpApi.Client(token="5f048fe")
* user = client.get_user(42)
*
* @apiSuccess {Number} id The Users-ID.
* @apiSuccess {Date} registered Registration Date.
* @apiSuccess {String} name Fullname of the User.
* @apiSuccess {String[]} nicknames List of Users nicknames (Array of Strings).
* @apiSuccess {Object} profile Profile data (example for an Object)
* @apiSuccess {Number} profile.age Users age.
* @apiSuccess {String} profile.image Avatar-Image.
* @apiSuccess {Object[]} options List of Users options (Array of Objects).
* @apiSuccess {String} options.name Option Name.
* @apiSuccess {String} options.value Option Value.
*
* @apiError NoAccessRight Only authenticated Admins can access the data.
* @apiError UserNotFound The <code>id</code> of the User was not found.
* @apiError (500 Internal Server Error) InternalServerError The server encountered an internal error
*
* @apiErrorExample Response (example):
* HTTP/1.1 401 Not Authenticated
* {
* "error": "NoAccessRight"
* }
*/
function getUser () { }
/**
* @api {post} /user Create a new User
* @apiVersion 0.3.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 {Number} age Age of the User
* @apiBody {String} name=Caroline Name of the User
* @apiBody {Object} extraInfo Date when user was hired
* @apiBody {Date} extraInfo.hireDate Date when user was hired
* @apiBody {Date} extraInfo.hireDateWithDefault=2021-09-01 Date when user was hired with default
* @apiBody {String[]} extraInfo.nicknames List of Users nicknames (Array of Strings)
* @apiBody {Boolean} extraInfo.isVegan=true Is the user vegan? (boolean with default)
* @apiBody {Object} extraInfo.secrets Secret object
* @apiBody {String} extraInfo.secrets.crush The user secret crush
* @apiBody {Number} extraInfo.secrets.hair=1000 Number of hair of user
* @apiBody {Object[]} extraInfo.secrets.deepSecrets Deep user secrets crush (array of objects)
* @apiBody {String} extraInfo.secrets.deepSecrets.key A deep user secret key
* @apiBody {Number} extraInfo.secrets.deepSecrets.number A deep user secret key
* @apiBody {String} extraInfo.secrets.deepSecrets.name.particle A deep user secret name particle with dot
* @apiBody {Boolean} extraInfo.isAlive Is the user alive? (boolean with no default)
* @apiBody {String} custom.property Custom property with dot
*
* @apiSuccess {Number} id The new Users-ID.
*
* @apiUse CreateUserError
*/
function postUser () { }
/**
* @api {put} /user/:id Change a User
* @apiVersion 0.3.0
* @apiName PutUser
* @apiGroup User
* @apiPermission none
*
* @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiErrorStructure"
*
* @apiParam {Number} id <code>id</code> of the user.
* @apiBody {String} name Name of the User.
* @apiBody {File} avatar Upload avatar.
*
* @apiUse CreateUserError
*/
function putUser () { }
/**
* @api {delete} /user/:id Delete user
* @apiVersion 0.3.0
* @apiName DeleteUser
* @apiGroup User
* @apiPermission admin
*
* @apiDescription Be careful! This will remove all the data associated with that user!
*
* @apiHeader {String} Authorization The token can be generated from your user profile.
* @apiHeaderExample {Header} Header-Example
* "Authorization: token 5f048fe"
* @apiParam {Number} id <code>id</code> of the user.
*
* @apiExample {bash} Curl example
* curl -X DELETE -H "Authorization: token 5f048fe" -i https://api.example.com/user/4711
* @apiExample {js} Javascript example
* const client = AcmeCorpApi('5f048fe');
* const user = client.deleteUser(42);
* @apiExample {python} Python example
* client = AcmeCorpApi.Client(token="5f048fe")
* user = client.delete_user(42)
*
* @apiSuccess {String} result <code>ok</code> if everything went fine.
* @apiSuccess {String} [nullableField] This response field is not always there (can be null).
* @apiSuccessExample {json} Success-Example
* HTTP/1.1 200 OK
* {
* "result": "ok"
* }
*
* @apiError NoAccessRight Only authenticated Admins can access the data.
* @apiError UserNotFound The <code>id</code> of the User was not found.
* @apiError (500 Internal Server Error) InternalServerError The server encountered an internal error.
*
* @apiErrorExample Response (example):
* HTTP/1.1 401 Not Authenticated
* {
* "error": "NoAccessRight"
* }
*/
function deleteUser () { }
/**
* @api {post} /user/:id Thank a user: this is quite a long name indeed
* @apiVersion 0.3.0
* @apiName ThankUser
* @apiGroup User
* @apiDescription This is here to have a long name in the left menu.
* @apiSampleRequest off
* @apiParam {Number} id <code>id</code> of the user.
*/
function thankUser () { }
/**
* @api {post} /city Create a new city
* @apiVersion 0.3.0
* @apiName CreateCity
* @apiGroup City
* @apiDescription Create a new city.
* @apiBody {String} name=Paris Name of the city
* @apiQuery {String=Aerial,Land,Underwater} view=Aerial Type of view.
* @apiQuery {Number} zoom Zoom.
*/
function createCity () { }
/**
* @api {get} /category Get a category
* @apiVersion 0.3.0
* @apiSampleRequest http://www.example.com
* @apiName GetCategory
* @apiGroup Category (official)
* @apiDescription Get a category. Sample request on example.com here.
* @apiQuery {Number} id Category ID.
* @apiBody {String} custom.id Custom ID with dot.
*/
function getCategory () { }
/**
* @api {delete} /category Delete a category
* @apiVersion 0.3.0
* @apiSampleRequest off
* @apiName DeleteCategory
* @apiGroup Category (official)
* @apiDescription Delete a category. Sample request has been disabled here.
* @apiQuery {Number} id Category ID.
* @apiParamExample {json} Some json code:
* {
* "user": "Sample User",
* "payload": {
* "test": [
* "code": "
* public class HelloWorldTest {
* HelloWorld hw = new HelloWorld();
* @Test
* public void testOkay {
* assertEquals(\"HelloWorld\", hw.getMsg());
* }
* }"
* ]
* }
* }
*/
function deleteCategory () { }