├── examples
    └── v0.1
    │   ├── api_project.json
    │   ├── api_project.js
    │   ├── api_data.json
    │   └── api_data.js
├── README.md
├── LICENSE.md
└── specs
    └── v0.1.md


/examples/v0.1/api_project.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "apidoc-example",
 3 |   "version": "0.3.0",
 4 |   "description": "apiDoc example project",
 5 |   "title": "Custom apiDoc browser title",
 6 |   "url": "https://api.github.com/v1",
 7 |   "sampleUrl": "https://playground.github.com/v1",
 8 |   "generator": {
 9 |     "version": "0.7.1",
10 |     "time": "2014-08-22T16:15:45.522Z"
11 |   },
12 |   "template": {
13 |     "withCompare": true,
14 |     "withGenerator": true
15 |   },
16 |   "header": {
17 |     "title": "Introduction",
18 |     "content": "<p>Please visit <a href=\"http://apidocjs.com\">apidocjs.com</a> for the full documentation.</p>\n"
19 |   },
20 |   "footer": {
21 |     "title": "Epilogue",
22 |     "content": "<p>Suggestions, contact, support and error reporting on <a href=\"https://github.com/apidoc/apidoc/issues\">GitHub</a></p>\n"
23 |   }
24 | }


--------------------------------------------------------------------------------
/examples/v0.1/api_project.js:
--------------------------------------------------------------------------------
 1 | define({
 2 |   "name": "apidoc-example",
 3 |   "version": "0.3.0",
 4 |   "description": "apiDoc example project",
 5 |   "title": "Custom apiDoc browser title",
 6 |   "url": "https://api.github.com/v1",
 7 |   "sampleUrl": "https://playground.github.com/v1",
 8 |   "generator": {
 9 |     "version": "0.7.1",
10 |     "time": "2014-08-22T16:15:45.522Z"
11 |   },
12 |   "template": {
13 |     "withCompare": true,
14 |     "withGenerator": true
15 |   },
16 |   "header": {
17 |     "title": "Introduction",
18 |     "content": "<p>Please visit <a href=\"http://apidocjs.com\">apidocjs.com</a> for the full documentation.</p>\n"
19 |   },
20 |   "footer": {
21 |     "title": "Epilogue",
22 |     "content": "<p>Suggestions, contact, support and error reporting on <a href=\"https://github.com/apidoc/apidoc/issues\">GitHub</a></p>\n"
23 |   }
24 | });


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # apiDoc Specification
 2 | 
 3 | ## Welcome to apiDoc RESTful web API Documentation
 4 | 
 5 | This project describe the specification of apiDoc, more precisely, the format returned by [apidoc](https://github.com/apidoc/apidoc).
 6 | 
 7 | If you are an end user, please proceed to the [apidoc-documentation](http://apidocjs.com).
 8 | 
 9 | 
10 | ## Version 0.1
11 | 
12 | apidoc-spec has its own version history, independent from the [apidoc](https://github.com/apidoc/apidoc) documentation generator.
13 | 
14 | While apidoc-spec starts with version 0.1 the apidoc generator still is in version 0.x.
15 | 
16 | Each specification has its own file in the [specs/](specs/) dir and each contain the changes to the previous.
17 | 
18 | ### [apiDoc 0.1 Specification](specs/v0.1.md)
19 | 
20 | 
21 | ## Projects
22 | 
23 | - [apidoc](https://github.com/apidoc/apidoc) Documentation generator
24 | - [apidocjs.com](http://apidocjs.com) End user documentation
25 | - [grunt-apidoc](https://github.com/apidoc/grunt-apidoc) Grunt module
26 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2013-2014 inveris OHG
 2 | Author Peter Rottmann <rottmann@inveris.de>
 3 | Licensed under the MIT license.
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining
 6 | a copy of this software and associated documentation files (the
 7 | "Software"), to deal in the Software without restriction, including
 8 | without limitation the rights to use, copy, modify, merge, publish,
 9 | distribute, sublicense, and/or sell copies of the Software, and to
10 | permit persons to whom the Software is furnished to do so, subject to
11 | the following conditions:
12 | 
13 | The above copyright notice and this permission notice shall be
14 | included in all copies or substantial portions of the Software.
15 | 
16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 | 


--------------------------------------------------------------------------------
/specs/v0.1.md:
--------------------------------------------------------------------------------
  1 | # apiDoc Specification
  2 | 
  3 | ## Version 0.1
  4 | 
  5 | This file describes the format that is returned by [apidoc](https://github.com/apidoc/apidoc).
  6 | 
  7 | 
  8 | 
  9 | ## Format
 10 | 
 11 | apidoc response is represented as a JSON object and Javascript AMD Modul.
 12 | 
 13 | apidoc itself copy some template files to the destination dir too.
 14 | Only when lib/apidoc is directly included and parameter `--parse=true` is set, the json and javascript files will be returned.
 15 | 
 16 | JSON:
 17 | ```json
 18 | {
 19 |   "name": "apidoc-example",
 20 |   "version": "0.3.0",
 21 |   "description": "apiDoc example project",
 22 |   "generator": {
 23 |     "version": "0.7.1",
 24 |     "time": "2014-08-22T16:15:45.522Z"
 25 |   }
 26 | }
 27 | ```
 28 | 
 29 | Javascript AMD Modul:
 30 | ```javascript
 31 | define({
 32 |   "name": "apidoc-example",
 33 |   "version": "0.3.0",
 34 |   "description": "apiDoc example project",
 35 |   "generator": {
 36 |     "version": "0.7.1",
 37 |     "time": "2014-08-22T16:15:45.522Z"
 38 |   }
 39 | });
 40 | ```
 41 | 
 42 | 
 43 | 
 44 | ## Response
 45 | 
 46 | By default apidoc creates 4 files:
 47 | * `api_data.json` / `api_data.js` with the representation of the API
 48 | * `api_project.json` / `api_project.js` with the project description and documentation settings
 49 | 
 50 | 
 51 | 
 52 | ## Schema api_data
 53 | 
 54 | ### Example api_data
 55 | 
 56 | [Example file](../examples/v0.1/api_data.json)
 57 | 
 58 | 
 59 | 
 60 | ### Data array
 61 | 
 62 | The api_data root is an **array** that contain a list of objects (Endpoints).
 63 | 
 64 | | Name | Type | Description |
 65 | | ---- | ---- | ----------- |
 66 | | _object_ | [Endpoint](#endpoint-object) | Unique Endpoint. |
 67 | 
 68 | 
 69 | 
 70 | ### Endpoint object
 71 | 
 72 | Each Endpoint / Method **is unique**. Unique because of their **group, name and version**, not because of the _url_, the _url_ can change while the api is in development.
 73 | 
 74 | | Name | Type | Description |
 75 | | ---- | ---- | ----------- |
 76 | | group            | string   | Group of the endpoint. A group describe to which part of your application the endpoint belongs, e.g. `GET /user/:id/` and `POST /logout` could belong to the group `Account`.<br>In the default template the group is used to separate the endpoints under a main navigation point.<br>Example: `"User"` |
 77 | | name             | string   | Name of the endpoint.<br>Example: `"GetUser"`. |
 78 | | version          | string   | Version of the endpoint - [semver 2](http://semver.org). If no Version is supported set to `"0.0.0"`.<br>Example: `"0.3.0"` |
 79 | | type             | string   | Type of the endpoint. `"get"`, `"put"`, `"post"`, `"delete"`, ...  |
 80 | | url              | string   | Endpoint path, a relative path to the [projects base url](#project-object).<br>Example: `"/with/:id/do/something"` |
 81 | | title            | string   | Title of the endpoint. |
 82 | | description      | string   | Endpoint description. HTML capable. |
 83 | | groupDescription | [string] | Group description. HTML capable. |
 84 | | filename         | string   | Relative filename of the documentation position in the source file. |
 85 | | permission       | [[Permission](#permission-object)]       | Permission object. |
 86 | | parameter        | [[Parameter](#parameter-object)]         | Parameter object. |
 87 | | success          | [[Success](#success-object)]             | Success object. |
 88 | | error            | [[Error](#error-object)]                 | Error object. |
 89 | | header           | [[Header](#header-object)]               | Header object. |
 90 | | examples         | [[Examples](#examples-array)]            | List of examples. |
 91 | | sampleRequest    | [[SampleRequest](#sample-request-array)] | List of sample request objects, to test the the API. |
 92 | 
 93 | 
 94 | ### Permission object
 95 | 
 96 | Describes the permissions to access the endpoint.
 97 | 
 98 | | Name | Type | Description |
 99 | | ---- | ---- | ----------- |
100 | | name        | string | Name of the permission.<br>Example: `"admin"` |
101 | | title       | string | Title of the permission.<br>Example: `"Admin access rights needed."` |
102 | | description | string | Permission description. HTML capable. |
103 | 
104 | 
105 | 
106 | ### Parameter object
107 | 
108 | Contains information about the parameters transfered to the endpoint.
109 | 
110 | | Name | Type | Description |
111 | | ---- | ---- | ----------- |
112 | | fields | [Fields](#fields-object) | Fields object. |
113 | _For historical reasons, the Parameter object did not have an examples array (compared to the Success, Error, Header object)._
114 | 
115 | 
116 | 
117 | ### Success object
118 | 
119 | Contains information about the success response from the server.
120 | 
121 | | Name | Type | Description |
122 | | ---- | ---- | ----------- |
123 | | fields   | [Fields](#fields-object) | Fields object. |
124 | | examples | [Examples](#examples-array) | Examples array. |
125 | 
126 | 
127 | 
128 | ### Error object
129 | 
130 | Contains information about the error response from the server.
131 | 
132 | | Name | Type | Description |
133 | | ---- | ---- | ----------- |
134 | | fields   | [Fields](#fields-object) | Fields object. |
135 | | examples | [Examples](#examples-array) | Examples array. |
136 | 
137 | 
138 | 
139 | ### Header object
140 | 
141 | Contains information about the header transfered to the endpoint.
142 | 
143 | | Name | Type | Description |
144 | | ---- | ---- | ----------- |
145 | | fields   | [Fields](#fields-object) | Fields object. |
146 | | examples | [Examples](#examples-array) | Examples array. |
147 | 
148 | 
149 | 
150 | ### Examples array
151 | 
152 | A **list of objects** that contain examples to access the Endpoint.
153 | 
154 | | Name | Type | Description |
155 | | ---- | ---- | ----------- |
156 | | _object_ | [Example](#example-object) | Example object. |
157 | 
158 | 
159 | 
160 | ### Sample Request array
161 | 
162 | A **list of objects** that contain sample URL to test the Endpoint from within the documentation.
163 | 
164 | | Name | Type | Description |
165 | | ---- | ---- | ----------- |
166 | | _object_ | [Example](#sample-request-object) | Sample Request object. |
167 | 
168 | 
169 | 
170 | ### Example object
171 | 
172 | Example to access the Endpoint.
173 | 
174 | | Name | Type | Description |
175 | | ---- | ---- | ----------- |
176 | | title   | string | Title of the example.<br>Example: `"Example usage with CURL:"` |
177 | | content | string | Example code to access the endpoint. |
178 | | type    | [string] | The code style of the content: `"curl"`, `"json"`, `"yaml"`, ...  |
179 | 
180 | 
181 | 
182 | ### Sample Request object
183 | 
184 | Test the Endpoint from within the documentation.
185 | 
186 | | Name | Type | Description |
187 | | ---- | ---- | ----------- |
188 | | url | string | URL of the Endpoint. |
189 | 
190 | 
191 | 
192 | ### Fields object
193 | 
194 | Contains variable named arrays. The _label_ is the group of a field (more exactly the label of a group).
195 | 
196 | The _label_ could be empty `""`, if no grouping is needed.
197 | 
198 | | Name | Type | Description |
199 | | ---- | ---- | ----------- |
200 | | _label_ | [Field](#field-object) | Field object. |
201 | 
202 | Example: `"This is a group"` is the variable _label_
203 | 
204 | ```json
205 | "fields": {
206 |   "This is a group": [
207 |     {
208 |       "group": "MyGroup",
209 |       "type": "String",
210 |       "field": "id",
211 |       "optional": false,
212 |       "description": "<p>The Users-ID.</p>"
213 |     }
214 |   ]
215 | }
216 | ```
217 | _Hint: Yes it was a stupid idea, it was implemented because of the simpler processing in the handlebar template and will definitely changed in a future version._
218 | 
219 | 
220 | 
221 | ### Field object
222 | 
223 | A single parameter field.
224 | 
225 | | Name | Type | Description |
226 | | ---- | ---- | ----------- |
227 | | group        | string  | Group name of the field. The group is used for a grouped output of all fields that belong to a group, e.g. it can be used to show public and private fields. |
228 | | type         | string  | User defined field type, `"String"`, `"Number"`, `"Boolean"` |
229 | | field        | string  | Name of the.<br>Example: `"firstname"` |
230 | | optional     | boolean | Is the field optional. |
231 | | defaultValue | mixed   | The default value of the field. |
232 | | description  | string  | Description of the field. HTML capable. |
233 | 
234 | 
235 | 
236 | ## Schema api_project
237 | 
238 | ### Example api_project
239 | 
240 | [Example file](../examples/v0.1/api_project.json)
241 | 
242 | ```json
243 | {
244 |   "name": "apidoc-example",
245 |   "version": "0.3.0",
246 |   "description": "apiDoc example project",
247 |   "title": "Custom apiDoc browser title",
248 |   "url": "https://api.github.com/v1",
249 |   "sampleUrl": "https://playground.github.com/v1",
250 |   "generator": {
251 |     "version": "0.7.1",
252 |     "time": "2014-08-22T16:15:45.522Z"
253 |   },
254 |   "template": {
255 |     "withCompare": true,
256 |     "withGenerator": true
257 |   },
258 |   "header": {
259 |     "title": "Introduction",
260 |     "content": "<p>Please visit <a href=\"http://apidocjs.com\">apidocjs.com</a> for the full documentation.</p>\n"
261 |   },
262 |   "footer": {
263 |     "title": "Epilogue",
264 |     "content": "<p>Suggestions, contact, support and error reporting on <a href=\"https://github.com/apidoc/apidoc/issues\">GitHub</a></p>\n"
265 |   }
266 | }
267 | ```
268 | 
269 | 
270 | 
271 | ### Project object
272 | 
273 | | Name | Type | Description |
274 | | ---- | ---- | ----------- |
275 | | name          | string   | Name of the application. |
276 | | version       | string   | Version of the application (*not the apiDoc Specification or Generator version!*) - [semver 2](http://semver.org).<br>Example: `"0.3.0"` |
277 | | description   | string   | Project description. It is used as introduction at the beginning of the documentation. |
278 | | title         | [string] | Browser title. |
279 | | url           | [string] | Public URL to access the API (prefix URL for an endpoint).<br>Example: `"https://api.github.com/v1"` |
280 | | sampleUrl     | [string] | Public URL to test the API.<br>Example: `"https://playground.github.com/v1"` |
281 | | generator     | [[Generator](#generator-object)] | Provides generator informations. |
282 | | template      | [[Template](#template-object)]   | Template specific settings. |
283 | | header        | [[Header](#header-object)]       | Additional content for the top of the documentation. |
284 | | footer        | [[Footer](footer-object)]        | Additional content for the bottom of the documentation. |
285 | 
286 | 
287 | 
288 | ### Generator object
289 | 
290 | Provides generator informations.
291 | 
292 | | Name | Type | Description |
293 | | ---- | ---- | ----------- |
294 | | version | string | Version of the generator (*not the apiDoc Specification version!*) - [semver 2](http://semver.org).<br>Example: `"0.7.1"` |
295 | | time    | string | Date-time when the representation file was created - [ECMA-262](http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15).<br>Example: `"2014-08-22T16:15:45.522Z"` |
296 | 
297 | 
298 | 
299 | ### Template object
300 | 
301 | Template specific settings.
302 | This settings belong to the default template.
303 | 
304 | | Name | Type | Default | Description |
305 | | ---- | ---- | ------- | ----------- |
306 | | withCompare   | [boolean] | true | Enable version compare function.
307 | | withGenerator | [boolean] | true | Append generator information at the bottom of the page.
308 | 
309 | 
310 | 
311 | ### Header object
312 | 
313 | An optional introduction section. The usage depend on the template.
314 | 
315 | | Name | Type | Default | Description |
316 | | ---- | ---- | ------- | ----------- |
317 | | title   | [string] | "General" | The title is used as the navigation label in default template.
318 | | content | [string] | ""        | HTML content appended to the top of the documentation.
319 | 
320 | 
321 | 
322 | ### Footer object
323 | 
324 | An optional epilogue. The usage depend on the template.
325 | 
326 | | Name | Type | Default | Description |
327 | | ---- | ---- | ------- | ----------- |
328 | | title   | [string] |  | The title is used as the navigation label in default template.
329 | | content | [string] |  | HTML content appended to the bottom of the documentation.
330 | 


--------------------------------------------------------------------------------
/examples/v0.1/api_data.json:
--------------------------------------------------------------------------------
  1 | [
  2 |   {
  3 |     "type": "get",
  4 |     "url": "/user/:id",
  5 |     "title": "Read data of a User",
  6 |     "version": "0.3.0",
  7 |     "name": "GetUser",
  8 |     "group": "User",
  9 |     "permission": {
 10 |       "name": "admin",
 11 |       "title": "Admin access rights needed. ",
 12 |       "description": "Optionally you can write here further Informations about the permission.\n\nAn \"apiDefinePermission\"-block can have an \"apiVersion\", so you can attach the block to a specific version.\n"
 13 |     },
 14 |     "description": "<p>Compare Verison 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.</p>",
 15 |     "parameter": {
 16 |       "fields": {
 17 |         "Parameter": [
 18 |           {
 19 |             "group": "Parameter",
 20 |             "type": "String",
 21 |             "field": "id",
 22 |             "optional": false,
 23 |             "description": "<p>The Users-ID.</p>"
 24 |           }
 25 |         ]
 26 |       }
 27 |     },
 28 |     "examples": [
 29 |       {
 30 |         "title": "Example usage:",
 31 |         "content": "curl -i http://localhost/user/4711\n"
 32 |       }
 33 |     ],
 34 |     "success": {
 35 |       "fields": {
 36 |         "Success 200": [
 37 |           {
 38 |             "group": "Success 200",
 39 |             "type": "String",
 40 |             "field": "id",
 41 |             "optional": false,
 42 |             "description": "<p>The Users-ID.</p>"
 43 |           },
 44 |           {
 45 |             "group": "Success 200",
 46 |             "type": "Date",
 47 |             "field": "registered",
 48 |             "optional": false,
 49 |             "description": "<p>Registration Date.</p>"
 50 |           },
 51 |           {
 52 |             "group": "Success 200",
 53 |             "type": "Date",
 54 |             "field": "name",
 55 |             "optional": false,
 56 |             "description": "<p>Fullname of the User.</p>"
 57 |           },
 58 |           {
 59 |             "group": "Success 200",
 60 |             "type": "String[]",
 61 |             "field": "nicknames",
 62 |             "optional": false,
 63 |             "description": "<p>List of Users nicknames (Array of Strings).</p>"
 64 |           },
 65 |           {
 66 |             "group": "Success 200",
 67 |             "type": "Object",
 68 |             "field": "profile",
 69 |             "optional": false,
 70 |             "description": "<p>Profile data (example for an Object)</p>"
 71 |           },
 72 |           {
 73 |             "group": "Success 200",
 74 |             "type": "Number",
 75 |             "field": "profile.age",
 76 |             "optional": false,
 77 |             "description": "<p>Users age.</p>"
 78 |           },
 79 |           {
 80 |             "group": "Success 200",
 81 |             "type": "String",
 82 |             "field": "profile.image",
 83 |             "optional": false,
 84 |             "description": "<p>Avatar-Image.</p>"
 85 |           },
 86 |           {
 87 |             "group": "Success 200",
 88 |             "type": "Object[]",
 89 |             "field": "options",
 90 |             "optional": false,
 91 |             "description": "<p>List of Users options (Array of Objects).</p>"
 92 |           },
 93 |           {
 94 |             "group": "Success 200",
 95 |             "type": "String",
 96 |             "field": "options.name",
 97 |             "optional": false,
 98 |             "description": "<p>Option Name.</p>"
 99 |           },
100 |           {
101 |             "group": "Success 200",
102 |             "type": "String",
103 |             "field": "options.value",
104 |             "optional": false,
105 |             "description": "<p>Option Value.</p>"
106 |           }
107 |         ]
108 |       }
109 |     },
110 |     "error": {
111 |       "fields": {
112 |         "Error 4xx": [
113 |           {
114 |             "group": "Error 4xx",
115 |             "field": "NoAccessRight",
116 |             "optional": false,
117 |             "description": "<p>Only authenticated Admins can access the data.</p>"
118 |           },
119 |           {
120 |             "group": "Error 4xx",
121 |             "field": "UserNotFound",
122 |             "optional": false,
123 |             "description": "<p>The <code>id</code> of the User was not found.</p>"
124 |           }
125 |         ]
126 |       },
127 |       "examples": [
128 |         {
129 |           "title": "Response (example):",
130 |           "content": "   HTTP/1.1 401 Not Authenticated\n   {\n     \"error\": \"NoAccessRight\"\n   }\n"
131 |         }
132 |       ]
133 |     },
134 |     "filename": "source/example_full/example.js"
135 |   },
136 |   {
137 |     "type": "get",
138 |     "url": "/user/:id",
139 |     "title": "Read data of a User",
140 |     "version": "0.2.0",
141 |     "name": "GetUser",
142 |     "group": "User",
143 |     "permission": {
144 |       "name": "admin",
145 |       "title": "This title is visible in version 0.1.0 and 0.2.0",
146 |       "description": ""
147 |     },
148 |     "description": "<p>Here you can describe the function.Multilines are possible.</p>",
149 |     "parameter": {
150 |       "fields": {
151 |         "Parameter": [
152 |           {
153 |             "group": "Parameter",
154 |             "type": "String",
155 |             "field": "id",
156 |             "optional": false,
157 |             "description": "<p>The Users-ID.</p>"
158 |           }
159 |         ]
160 |       }
161 |     },
162 |     "success": {
163 |       "fields": {
164 |         "Success 200": [
165 |           {
166 |             "group": "Success 200",
167 |             "type": "String",
168 |             "field": "id",
169 |             "optional": false,
170 |             "description": "<p>The Users-ID.</p>"
171 |           },
172 |           {
173 |             "group": "Success 200",
174 |             "type": "Date",
175 |             "field": "name",
176 |             "optional": false,
177 |             "description": "<p>Fullname of the User.</p>"
178 |           }
179 |         ]
180 |       }
181 |     },
182 |     "error": {
183 |       "fields": {
184 |         "Error 4xx": [
185 |           {
186 |             "group": "Error 4xx",
187 |             "field": "UserNotFound",
188 |             "optional": false,
189 |             "description": "<p>The <code>id</code> of the User was not found.</p>"
190 |           }
191 |         ]
192 |       }
193 |     },
194 |     "filename": "source/example_full/_apidoc.js"
195 |   },
196 |   {
197 |     "type": "get",
198 |     "url": "/user/:id",
199 |     "title": "Read data of a User",
200 |     "version": "0.1.0",
201 |     "name": "GetUser",
202 |     "group": "User",
203 |     "permission": {
204 |       "name": "admin",
205 |       "title": "This title is visible in version 0.1.0 and 0.2.0",
206 |       "description": ""
207 |     },
208 |     "description": "<p>Here you can describe the function.Multilines are possible.</p>",
209 |     "parameter": {
210 |       "fields": {
211 |         "Parameter": [
212 |           {
213 |             "group": "Parameter",
214 |             "type": "String",
215 |             "field": "id",
216 |             "optional": false,
217 |             "description": "<p>The Users-ID.</p>"
218 |           }
219 |         ]
220 |       }
221 |     },
222 |     "success": {
223 |       "fields": {
224 |         "Success 200": [
225 |           {
226 |             "group": "Success 200",
227 |             "type": "String",
228 |             "field": "id",
229 |             "optional": false,
230 |             "description": "<p>The Users-ID.</p>"
231 |           },
232 |           {
233 |             "group": "Success 200",
234 |             "type": "Date",
235 |             "field": "name",
236 |             "optional": false,
237 |             "description": "<p>Fullname of the User.</p>"
238 |           }
239 |         ]
240 |       }
241 |     },
242 |     "error": {
243 |       "fields": {
244 |         "Error 4xx": [
245 |           {
246 |             "group": "Error 4xx",
247 |             "field": "UserNotFound",
248 |             "optional": false,
249 |             "description": "<p>The error description text in version 0.1.0.</p>"
250 |           }
251 |         ]
252 |       }
253 |     },
254 |     "filename": "source/example_full/_apidoc.js"
255 |   },
256 |   {
257 |     "type": "post",
258 |     "url": "/user",
259 |     "title": "Create a new User",
260 |     "version": "0.3.0",
261 |     "name": "PostUser",
262 |     "group": "User",
263 |     "permission": "none",
264 |     "description": "<p>In this case &quot;apiErrorStructure&quot; is defined and used.Define blocks with params that will be used in several functions, so you dont have to rewrite them.</p>",
265 |     "parameter": {
266 |       "fields": {
267 |         "Parameter": [
268 |           {
269 |             "group": "Parameter",
270 |             "type": "String",
271 |             "field": "name",
272 |             "optional": false,
273 |             "description": "<p>Name of the User.</p>"
274 |           }
275 |         ]
276 |       }
277 |     },
278 |     "success": {
279 |       "fields": {
280 |         "Success 200": [
281 |           {
282 |             "group": "Success 200",
283 |             "type": "String",
284 |             "field": "id",
285 |             "optional": false,
286 |             "description": "<p>The new Users-ID.</p>"
287 |           }
288 |         ]
289 |       }
290 |     },
291 |     "error": {
292 |       "fields": {
293 |         "Error 4xx": [
294 |           {
295 |             "group": "Error 4xx",
296 |             "field": "NoAccessRight",
297 |             "optional": false,
298 |             "description": "<p>Only authenticated Admins can access the data.</p>"
299 |           },
300 |           {
301 |             "group": "Error 4xx",
302 |             "field": "UserNameTooShort",
303 |             "optional": false,
304 |             "description": "<p>Minimum of 5 characters required.</p>"
305 |           }
306 |         ]
307 |       },
308 |       "examples": [
309 |         {
310 |           "title": " Response (example):",
311 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
312 |         }
313 |       ]
314 |     },
315 |     "filename": "source/example_full/example.js"
316 |   },
317 |   {
318 |     "type": "post",
319 |     "url": "/user",
320 |     "title": "Create a User",
321 |     "version": "0.2.0",
322 |     "name": "PostUser",
323 |     "group": "User",
324 |     "permission": "none",
325 |     "description": "<p>In this case &quot;apiErrorStructure&quot; is defined and used.Define blocks with params that will be used in several functions, so you dont have to rewrite them.</p>",
326 |     "parameter": {
327 |       "fields": {
328 |         "Parameter": [
329 |           {
330 |             "group": "Parameter",
331 |             "type": "String",
332 |             "field": "name",
333 |             "optional": false,
334 |             "description": "<p>Name of the User.</p>"
335 |           }
336 |         ]
337 |       }
338 |     },
339 |     "success": {
340 |       "fields": {
341 |         "Success 200": [
342 |           {
343 |             "group": "Success 200",
344 |             "type": "String",
345 |             "field": "id",
346 |             "optional": false,
347 |             "description": "<p>The Users-ID.</p>"
348 |           }
349 |         ]
350 |       }
351 |     },
352 |     "error": {
353 |       "fields": {
354 |         "Error 4xx": [
355 |           {
356 |             "group": "Error 4xx",
357 |             "field": "NoAccessRight",
358 |             "optional": false,
359 |             "description": "<p>Only authenticated Admins can access the data.</p>"
360 |           },
361 |           {
362 |             "group": "Error 4xx",
363 |             "field": "UserNameTooShort",
364 |             "optional": false,
365 |             "description": "<p>Minimum of 5 characters required.</p>"
366 |           }
367 |         ]
368 |       },
369 |       "examples": [
370 |         {
371 |           "title": " Response (example):",
372 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
373 |         }
374 |       ]
375 |     },
376 |     "filename": "source/example_full/_apidoc.js"
377 |   },
378 |   {
379 |     "type": "put",
380 |     "url": "/user/:id",
381 |     "title": "Change a new User",
382 |     "version": "0.3.0",
383 |     "name": "PutUser",
384 |     "group": "User",
385 |     "permission": "none",
386 |     "description": "<p>This function has same errors like POST /user, but errors not defined again, they were included with &quot;apiErrorStructure&quot;</p>",
387 |     "parameter": {
388 |       "fields": {
389 |         "Parameter": [
390 |           {
391 |             "group": "Parameter",
392 |             "type": "String",
393 |             "field": "name",
394 |             "optional": false,
395 |             "description": "<p>Name of the User.</p>"
396 |           }
397 |         ]
398 |       }
399 |     },
400 |     "error": {
401 |       "fields": {
402 |         "Error 4xx": [
403 |           {
404 |             "group": "Error 4xx",
405 |             "field": "NoAccessRight",
406 |             "optional": false,
407 |             "description": "<p>Only authenticated Admins can access the data.</p>"
408 |           },
409 |           {
410 |             "group": "Error 4xx",
411 |             "field": "UserNameTooShort",
412 |             "optional": false,
413 |             "description": "<p>Minimum of 5 characters required.</p>"
414 |           }
415 |         ]
416 |       },
417 |       "examples": [
418 |         {
419 |           "title": " Response (example):",
420 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
421 |         }
422 |       ]
423 |     },
424 |     "filename": "source/example_full/example.js"
425 |   },
426 |   {
427 |     "version": "0.3.0",
428 |     "group": "_apidoc.js",
429 |     "type": "",
430 |     "url": "",
431 |     "filename": "source/example_full/_apidoc.js"
432 |   },
433 |   {
434 |     "version": "0.2.0",
435 |     "error": {
436 |       "fields": {
437 |         "Error 4xx": [
438 |           {
439 |             "group": "Error 4xx",
440 |             "field": "NoAccessRight",
441 |             "optional": false,
442 |             "description": "<p>Only authenticated Admins can access the data.</p>"
443 |           },
444 |           {
445 |             "group": "Error 4xx",
446 |             "field": "UserNameTooShort",
447 |             "optional": false,
448 |             "description": "<p>Minimum of 5 characters required.</p>"
449 |           }
450 |         ]
451 |       },
452 |       "examples": [
453 |         {
454 |           "title": " Response (example):",
455 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
456 |         }
457 |       ]
458 |     },
459 |     "group": "_apidoc.js",
460 |     "type": "",
461 |     "url": "",
462 |     "filename": "source/example_full/_apidoc.js"
463 |   },
464 |   {
465 |     "version": "0.1.0",
466 |     "group": "_apidoc.js",
467 |     "type": "",
468 |     "url": "",
469 |     "filename": "source/example_full/_apidoc.js"
470 |   }
471 | ]


--------------------------------------------------------------------------------
/examples/v0.1/api_data.js:
--------------------------------------------------------------------------------
  1 | define({ api: [
  2 |   {
  3 |     "type": "get",
  4 |     "url": "/user/:id",
  5 |     "title": "Read data of a User",
  6 |     "version": "0.3.0",
  7 |     "name": "GetUser",
  8 |     "group": "User",
  9 |     "permission": {
 10 |       "name": "admin",
 11 |       "title": "Admin access rights needed. ",
 12 |       "description": "Optionally you can write here further Informations about the permission.\n\nAn \"apiDefinePermission\"-block can have an \"apiVersion\", so you can attach the block to a specific version.\n"
 13 |     },
 14 |     "description": "<p>Compare Verison 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.</p>",
 15 |     "parameter": {
 16 |       "fields": {
 17 |         "Parameter": [
 18 |           {
 19 |             "group": "Parameter",
 20 |             "type": "String",
 21 |             "field": "id",
 22 |             "optional": false,
 23 |             "description": "<p>The Users-ID.</p>"
 24 |           }
 25 |         ]
 26 |       }
 27 |     },
 28 |     "examples": [
 29 |       {
 30 |         "title": "Example usage:",
 31 |         "content": "curl -i http://localhost/user/4711\n"
 32 |       }
 33 |     ],
 34 |     "success": {
 35 |       "fields": {
 36 |         "Success 200": [
 37 |           {
 38 |             "group": "Success 200",
 39 |             "type": "String",
 40 |             "field": "id",
 41 |             "optional": false,
 42 |             "description": "<p>The Users-ID.</p>"
 43 |           },
 44 |           {
 45 |             "group": "Success 200",
 46 |             "type": "Date",
 47 |             "field": "registered",
 48 |             "optional": false,
 49 |             "description": "<p>Registration Date.</p>"
 50 |           },
 51 |           {
 52 |             "group": "Success 200",
 53 |             "type": "Date",
 54 |             "field": "name",
 55 |             "optional": false,
 56 |             "description": "<p>Fullname of the User.</p>"
 57 |           },
 58 |           {
 59 |             "group": "Success 200",
 60 |             "type": "String[]",
 61 |             "field": "nicknames",
 62 |             "optional": false,
 63 |             "description": "<p>List of Users nicknames (Array of Strings).</p>"
 64 |           },
 65 |           {
 66 |             "group": "Success 200",
 67 |             "type": "Object",
 68 |             "field": "profile",
 69 |             "optional": false,
 70 |             "description": "<p>Profile data (example for an Object)</p>"
 71 |           },
 72 |           {
 73 |             "group": "Success 200",
 74 |             "type": "Number",
 75 |             "field": "profile.age",
 76 |             "optional": false,
 77 |             "description": "<p>Users age.</p>"
 78 |           },
 79 |           {
 80 |             "group": "Success 200",
 81 |             "type": "String",
 82 |             "field": "profile.image",
 83 |             "optional": false,
 84 |             "description": "<p>Avatar-Image.</p>"
 85 |           },
 86 |           {
 87 |             "group": "Success 200",
 88 |             "type": "Object[]",
 89 |             "field": "options",
 90 |             "optional": false,
 91 |             "description": "<p>List of Users options (Array of Objects).</p>"
 92 |           },
 93 |           {
 94 |             "group": "Success 200",
 95 |             "type": "String",
 96 |             "field": "options.name",
 97 |             "optional": false,
 98 |             "description": "<p>Option Name.</p>"
 99 |           },
100 |           {
101 |             "group": "Success 200",
102 |             "type": "String",
103 |             "field": "options.value",
104 |             "optional": false,
105 |             "description": "<p>Option Value.</p>"
106 |           }
107 |         ]
108 |       }
109 |     },
110 |     "error": {
111 |       "fields": {
112 |         "Error 4xx": [
113 |           {
114 |             "group": "Error 4xx",
115 |             "field": "NoAccessRight",
116 |             "optional": false,
117 |             "description": "<p>Only authenticated Admins can access the data.</p>"
118 |           },
119 |           {
120 |             "group": "Error 4xx",
121 |             "field": "UserNotFound",
122 |             "optional": false,
123 |             "description": "<p>The <code>id</code> of the User was not found.</p>"
124 |           }
125 |         ]
126 |       },
127 |       "examples": [
128 |         {
129 |           "title": "Response (example):",
130 |           "content": "   HTTP/1.1 401 Not Authenticated\n   {\n     \"error\": \"NoAccessRight\"\n   }\n"
131 |         }
132 |       ]
133 |     },
134 |     "filename": "source/example_full/example.js"
135 |   },
136 |   {
137 |     "type": "get",
138 |     "url": "/user/:id",
139 |     "title": "Read data of a User",
140 |     "version": "0.2.0",
141 |     "name": "GetUser",
142 |     "group": "User",
143 |     "permission": {
144 |       "name": "admin",
145 |       "title": "This title is visible in version 0.1.0 and 0.2.0",
146 |       "description": ""
147 |     },
148 |     "description": "<p>Here you can describe the function.Multilines are possible.</p>",
149 |     "parameter": {
150 |       "fields": {
151 |         "Parameter": [
152 |           {
153 |             "group": "Parameter",
154 |             "type": "String",
155 |             "field": "id",
156 |             "optional": false,
157 |             "description": "<p>The Users-ID.</p>"
158 |           }
159 |         ]
160 |       }
161 |     },
162 |     "success": {
163 |       "fields": {
164 |         "Success 200": [
165 |           {
166 |             "group": "Success 200",
167 |             "type": "String",
168 |             "field": "id",
169 |             "optional": false,
170 |             "description": "<p>The Users-ID.</p>"
171 |           },
172 |           {
173 |             "group": "Success 200",
174 |             "type": "Date",
175 |             "field": "name",
176 |             "optional": false,
177 |             "description": "<p>Fullname of the User.</p>"
178 |           }
179 |         ]
180 |       }
181 |     },
182 |     "error": {
183 |       "fields": {
184 |         "Error 4xx": [
185 |           {
186 |             "group": "Error 4xx",
187 |             "field": "UserNotFound",
188 |             "optional": false,
189 |             "description": "<p>The <code>id</code> of the User was not found.</p>"
190 |           }
191 |         ]
192 |       }
193 |     },
194 |     "filename": "source/example_full/_apidoc.js"
195 |   },
196 |   {
197 |     "type": "get",
198 |     "url": "/user/:id",
199 |     "title": "Read data of a User",
200 |     "version": "0.1.0",
201 |     "name": "GetUser",
202 |     "group": "User",
203 |     "permission": {
204 |       "name": "admin",
205 |       "title": "This title is visible in version 0.1.0 and 0.2.0",
206 |       "description": ""
207 |     },
208 |     "description": "<p>Here you can describe the function.Multilines are possible.</p>",
209 |     "parameter": {
210 |       "fields": {
211 |         "Parameter": [
212 |           {
213 |             "group": "Parameter",
214 |             "type": "String",
215 |             "field": "id",
216 |             "optional": false,
217 |             "description": "<p>The Users-ID.</p>"
218 |           }
219 |         ]
220 |       }
221 |     },
222 |     "success": {
223 |       "fields": {
224 |         "Success 200": [
225 |           {
226 |             "group": "Success 200",
227 |             "type": "String",
228 |             "field": "id",
229 |             "optional": false,
230 |             "description": "<p>The Users-ID.</p>"
231 |           },
232 |           {
233 |             "group": "Success 200",
234 |             "type": "Date",
235 |             "field": "name",
236 |             "optional": false,
237 |             "description": "<p>Fullname of the User.</p>"
238 |           }
239 |         ]
240 |       }
241 |     },
242 |     "error": {
243 |       "fields": {
244 |         "Error 4xx": [
245 |           {
246 |             "group": "Error 4xx",
247 |             "field": "UserNotFound",
248 |             "optional": false,
249 |             "description": "<p>The error description text in version 0.1.0.</p>"
250 |           }
251 |         ]
252 |       }
253 |     },
254 |     "filename": "source/example_full/_apidoc.js"
255 |   },
256 |   {
257 |     "type": "post",
258 |     "url": "/user",
259 |     "title": "Create a new User",
260 |     "version": "0.3.0",
261 |     "name": "PostUser",
262 |     "group": "User",
263 |     "permission": "none",
264 |     "description": "<p>In this case &quot;apiErrorStructure&quot; is defined and used.Define blocks with params that will be used in several functions, so you dont have to rewrite them.</p>",
265 |     "parameter": {
266 |       "fields": {
267 |         "Parameter": [
268 |           {
269 |             "group": "Parameter",
270 |             "type": "String",
271 |             "field": "name",
272 |             "optional": false,
273 |             "description": "<p>Name of the User.</p>"
274 |           }
275 |         ]
276 |       }
277 |     },
278 |     "success": {
279 |       "fields": {
280 |         "Success 200": [
281 |           {
282 |             "group": "Success 200",
283 |             "type": "String",
284 |             "field": "id",
285 |             "optional": false,
286 |             "description": "<p>The new Users-ID.</p>"
287 |           }
288 |         ]
289 |       }
290 |     },
291 |     "error": {
292 |       "fields": {
293 |         "Error 4xx": [
294 |           {
295 |             "group": "Error 4xx",
296 |             "field": "NoAccessRight",
297 |             "optional": false,
298 |             "description": "<p>Only authenticated Admins can access the data.</p>"
299 |           },
300 |           {
301 |             "group": "Error 4xx",
302 |             "field": "UserNameTooShort",
303 |             "optional": false,
304 |             "description": "<p>Minimum of 5 characters required.</p>"
305 |           }
306 |         ]
307 |       },
308 |       "examples": [
309 |         {
310 |           "title": " Response (example):",
311 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
312 |         }
313 |       ]
314 |     },
315 |     "filename": "source/example_full/example.js"
316 |   },
317 |   {
318 |     "type": "post",
319 |     "url": "/user",
320 |     "title": "Create a User",
321 |     "version": "0.2.0",
322 |     "name": "PostUser",
323 |     "group": "User",
324 |     "permission": "none",
325 |     "description": "<p>In this case &quot;apiErrorStructure&quot; is defined and used.Define blocks with params that will be used in several functions, so you dont have to rewrite them.</p>",
326 |     "parameter": {
327 |       "fields": {
328 |         "Parameter": [
329 |           {
330 |             "group": "Parameter",
331 |             "type": "String",
332 |             "field": "name",
333 |             "optional": false,
334 |             "description": "<p>Name of the User.</p>"
335 |           }
336 |         ]
337 |       }
338 |     },
339 |     "success": {
340 |       "fields": {
341 |         "Success 200": [
342 |           {
343 |             "group": "Success 200",
344 |             "type": "String",
345 |             "field": "id",
346 |             "optional": false,
347 |             "description": "<p>The Users-ID.</p>"
348 |           }
349 |         ]
350 |       }
351 |     },
352 |     "error": {
353 |       "fields": {
354 |         "Error 4xx": [
355 |           {
356 |             "group": "Error 4xx",
357 |             "field": "NoAccessRight",
358 |             "optional": false,
359 |             "description": "<p>Only authenticated Admins can access the data.</p>"
360 |           },
361 |           {
362 |             "group": "Error 4xx",
363 |             "field": "UserNameTooShort",
364 |             "optional": false,
365 |             "description": "<p>Minimum of 5 characters required.</p>"
366 |           }
367 |         ]
368 |       },
369 |       "examples": [
370 |         {
371 |           "title": " Response (example):",
372 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
373 |         }
374 |       ]
375 |     },
376 |     "filename": "source/example_full/_apidoc.js"
377 |   },
378 |   {
379 |     "type": "put",
380 |     "url": "/user/:id",
381 |     "title": "Change a new User",
382 |     "version": "0.3.0",
383 |     "name": "PutUser",
384 |     "group": "User",
385 |     "permission": "none",
386 |     "description": "<p>This function has same errors like POST /user, but errors not defined again, they were included with &quot;apiErrorStructure&quot;</p>",
387 |     "parameter": {
388 |       "fields": {
389 |         "Parameter": [
390 |           {
391 |             "group": "Parameter",
392 |             "type": "String",
393 |             "field": "name",
394 |             "optional": false,
395 |             "description": "<p>Name of the User.</p>"
396 |           }
397 |         ]
398 |       }
399 |     },
400 |     "error": {
401 |       "fields": {
402 |         "Error 4xx": [
403 |           {
404 |             "group": "Error 4xx",
405 |             "field": "NoAccessRight",
406 |             "optional": false,
407 |             "description": "<p>Only authenticated Admins can access the data.</p>"
408 |           },
409 |           {
410 |             "group": "Error 4xx",
411 |             "field": "UserNameTooShort",
412 |             "optional": false,
413 |             "description": "<p>Minimum of 5 characters required.</p>"
414 |           }
415 |         ]
416 |       },
417 |       "examples": [
418 |         {
419 |           "title": " Response (example):",
420 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
421 |         }
422 |       ]
423 |     },
424 |     "filename": "source/example_full/example.js"
425 |   },
426 |   {
427 |     "version": "0.3.0",
428 |     "group": "_apidoc.js",
429 |     "type": "",
430 |     "url": "",
431 |     "filename": "source/example_full/_apidoc.js"
432 |   },
433 |   {
434 |     "version": "0.2.0",
435 |     "error": {
436 |       "fields": {
437 |         "Error 4xx": [
438 |           {
439 |             "group": "Error 4xx",
440 |             "field": "NoAccessRight",
441 |             "optional": false,
442 |             "description": "<p>Only authenticated Admins can access the data.</p>"
443 |           },
444 |           {
445 |             "group": "Error 4xx",
446 |             "field": "UserNameTooShort",
447 |             "optional": false,
448 |             "description": "<p>Minimum of 5 characters required.</p>"
449 |           }
450 |         ]
451 |       },
452 |       "examples": [
453 |         {
454 |           "title": " Response (example):",
455 |           "content": "   HTTP/1.1 400 Bad Request\n   {\n     \"error\": \"UserNameTooShort\"\n   }\n"
456 |         }
457 |       ]
458 |     },
459 |     "group": "_apidoc.js",
460 |     "type": "",
461 |     "url": "",
462 |     "filename": "source/example_full/_apidoc.js"
463 |   },
464 |   {
465 |     "version": "0.1.0",
466 |     "group": "_apidoc.js",
467 |     "type": "",
468 |     "url": "",
469 |     "filename": "source/example_full/_apidoc.js"
470 |   }
471 | ] });


--------------------------------------------------------------------------------