Skip to content

Add apiBody and apiQuery to the docs #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 20, 2021
Merged

Add apiBody and apiQuery to the docs #34

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 185 additions & 2 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,9 @@ <h3>apiDoc creates a documentation from API annotations in your source code.</h3
# @api {get} /user/:id Request User information
# @apiName GetUser
# @apiGroup User
#
#
# @apiParam {Number} id Users unique ID.
#
#
# @apiSuccess {String} firstname Firstname of the User.
# @apiSuccess {String} lastname Lastname of the User.
# }</code></pre>
Expand Down Expand Up @@ -837,6 +837,106 @@ <h2>@api</h2>
*/</code></pre>
</article>

<!-- ============================================================ -->

<article id="param-api-body">
<h2>@apiBody</h2>
<pre><code>@apiBody [{type}] [field=defaultValue] [description]</code></pre>
<p>Describe the request body passed to your API-Method.</p>
<p>Usage: <code>@apiBody {type} {key: value}</code></p>

<table>
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="code">{type}<span class="label label-optional">optional</span></td>
<td>
Parameter type, e.g. <code>{Boolean}</code>, <code>{Number}</code>, <code>{String}</code>, <code>{Object}</code>, <code>{String[]}</code> (array of strings), ...
</td>
</tr>
<tr>
<td class="code">{type{size}}<span class="label label-optional">optional</span></td>
<td>
Information about the size of the variable.<br>
<code>{string{..5}}</code> a string that has max 5 chars.<br>
<code>{string{2..5}}</code> a string that has min. 2 chars and max 5 chars.<br>
<code>{number{100-999}}</code> a number between 100 and 999.<br>
</td>
</tr>
<tr>
<td class="code">{type=allowedValues}<span class="label label-optional">optional</span></td>
<td>
Information about allowed values of the variable.<br>
<code>{string="small"}</code> a string that can only contain the word "small" (a constant).<br>
<code>{string="small","huge"}</code> a string that can contain the words "small" or "huge".<br>
<code>{number=1,2,3,99}</code> a number with allowed values of 1, 2, 3 and 99.<br>
<br>
Can be combined with size:<br>
<code>{string {..5}="small","huge"}</code> a string that has max 5 chars and only contain the words "small" or "huge".<br>
</td>
</tr>
<tr>
<td class="code">field</td>
<td>
Fieldname.
</td>
</tr>
<tr>
<td class="code">[field]</td>
<td>
Fieldname with brackets define the Variable as optional.
</td>
</tr>
<tr>
<td class="code">field[nestedField]</td>
<td>
Mandatory nested field.
</td>
</tr>
<tr>
<td class="code">=defaultValue<span class="label label-optional">optional</span></td>
<td>
The parameters default value.
</td>
</tr>
<tr>
<td class="code">description<span class="label label-optional">optional</span></td>
<td>
Description of the field.
</td>
</tr>
</tbody>
</table>

<p>Examples:</p>
<pre class="example"><code>/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/

/**
* @api {post} /user/
* @apiParam {String} [firstname] Optional Firstname of the User.
* @apiParam {String} lastname Mandatory Lastname.
* @apiParam {String} country="DE" Mandatory with default value "DE".
* @apiParam {Number} [age=18] Optional Age with default 18.
*
* @apiParam (Login) {String} pass Only logged in users can post this.
* In generated documentation a separate
* "Login" Block will be generated.
*
* @apiParam {Object} [address] Optional nested address object.
* @apiParam {String} [address[street]] Optional street and number.
* @apiParam {String} [address[zip]] Optional zip code.
* @apiParam {String} [address[city]] Optional city.
*/</code></pre>
</article>

<!-- ============================================================ -->

<article id="param-api-define">
Expand Down Expand Up @@ -1541,6 +1641,89 @@ <h2>@apiPrivate</h2>
*/</code></pre>
</article>

<!-- ============================================================ -->

<article id="param-api-query">
<h2>@apiBody</h2>
<pre><code>@apiQuery [{type}] [field=defaultValue] [description]</code></pre>
<p>Describe a query parameter passed to your API-Method.</p>
<p>Usage: <code>@apiQuery {Number} id Users unique ID.</code></p>

<table>
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="code">{type}<span class="label label-optional">optional</span></td>
<td>
Parameter type, e.g. <code>{Boolean}</code>, <code>{Number}</code>, <code>{String}</code>, <code>{Object}</code>, <code>{String[]}</code> (array of strings), ...
</td>
</tr>
<tr>
<td class="code">{type{size}}<span class="label label-optional">optional</span></td>
<td>
Information about the size of the variable.<br>
<code>{string{..5}}</code> a string that has max 5 chars.<br>
<code>{string{2..5}}</code> a string that has min. 2 chars and max 5 chars.<br>
<code>{number{100-999}}</code> a number between 100 and 999.<br>
</td>
</tr>
<tr>
<td class="code">{type=allowedValues}<span class="label label-optional">optional</span></td>
<td>
Information about allowed values of the variable.<br>
<code>{string="small"}</code> a string that can only contain the word "small" (a constant).<br>
<code>{string="small","huge"}</code> a string that can contain the words "small" or "huge".<br>
<code>{number=1,2,3,99}</code> a number with allowed values of 1, 2, 3 and 99.<br>
<br>
Can be combined with size:<br>
<code>{string {..5}="small","huge"}</code> a string that has max 5 chars and only contain the words "small" or "huge".<br>
</td>
</tr>
<tr>
<td class="code">field</td>
<td>
Fieldname.
</td>
</tr>
<tr>
<td class="code">[field]</td>
<td>
Fieldname with brackets define the Variable as optional.
</td>
</tr>
<tr>
<td class="code">field[nestedField]</td>
<td>
Mandatory nested field.
</td>
</tr>
<tr>
<td class="code">=defaultValue<span class="label label-optional">optional</span></td>
<td>
The parameters default value.
</td>
</tr>
<tr>
<td class="code">description<span class="label label-optional">optional</span></td>
<td>
Description of the field.
</td>
</tr>
</tbody>
</table>

<p>Examples:</p>
<pre class="example"><code>/**
* @api {get} /user/:id
* @apiQuery admin
*/</code></pre>
</article>

<!-- ============================================================ -->

<article id="param-api-sample-request">
Expand Down