491bcb86ed
String.prototype.substr() is deprecated (see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr) so we replace it with slice() which works similarily but isn't deprecated. Signed-off-by: Tobias Speicher <rootcommander@gmail.com> |
||
|---|---|---|
| .. | ||
| README.md | ||
| generate.js | ||
| toSwagger.js | ||
README.md
Documentation
This directory contains the scripts required to generate the APIDoc based documentation. You can find the docs about comment structure at the APIDocs page.
In general most API endpoints will look like:
/**
* @api {post} /api/:param/url Give it a name
* @apiName Give it a name
* @apiGroup group
* @apiPermission permission
* @apiDescription Describe what the endpoint does, any special cases the user
* should be aware of.
*
* @apiParam {string} param describe a URL parameter.
*
* @apiParam (Body) input describe a field on the body.
*
* @apiSuccess {object} output describe the output.
*/
There are a few key points to note when writing API docs:
- Don't use
@apiBody- this isn't currently supported by our swagger converter. - Make sure to always have an
@apidefinition at the start, which must always have the HTTP verb, the endpoint URL and the name. - There are three ways you can specify parameters used as inputs for your endpoint,
@apiParamfor a URL param,@apiParam (Body)for a field on the request body and@apiParam (Query)for query string parameters. - The
@apiGroupshould be the same for all API Doc comments in a route file.