Skip to content

Commit 681f00a

Browse files
NicolasCARPiNicolasCARPi
authored
Merge pull request #34 from SWheeler17/gh-pages
Add apiBody and apiQuery to the docs
2 parents 4dde7aa + 650f1e4 commit 681f00a

File tree

1 file changed

+185
-2
lines changed

1 file changed

+185
-2
lines changed

‎index.html

Lines changed: 185 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,9 +75,9 @@ <h3>apiDoc creates a documentation from API annotations in your source code.</h3
7575
# @api {get} /user/:id Request User information
7676
# @apiName GetUser
7777
# @apiGroup User
78-
#
78+
#
7979
# @apiParam {Number} id Users unique ID.
80-
#
80+
#
8181
# @apiSuccess {String} firstname Firstname of the User.
8282
# @apiSuccess {String} lastname Lastname of the User.
8383
# }</code></pre>
@@ -850,6 +850,106 @@ <h2>@api</h2>
850850
*/</code></pre>
851851
</article>
852852

853+
<!-- ============================================================ -->
854+
855+
<article id="param-api-body">
856+
<h2>@apiBody</h2>
857+
<pre><code>@apiBody [{type}] [field=defaultValue] [description]</code></pre>
858+
<p>Describe the request body passed to your API-Method.</p>
859+
<p>Usage: <code>@apiBody {type} {key: value}</code></p>
860+
861+
<table>
862+
<thead>
863+
<tr>
864+
<th>Name</th>
865+
<th>Description</th>
866+
</tr>
867+
</thead>
868+
<tbody>
869+
<tr>
870+
<td class="code">{type}<span class="label label-optional">optional</span></td>
871+
<td>
872+
Parameter type, e.g. <code>{Boolean}</code>, <code>{Number}</code>, <code>{String}</code>, <code>{Object}</code>, <code>{String[]}</code> (array of strings), ...
873+
</td>
874+
</tr>
875+
<tr>
876+
<td class="code">{type{size}}<span class="label label-optional">optional</span></td>
877+
<td>
878+
Information about the size of the variable.<br>
879+
<code>{string{..5}}</code> a string that has max 5 chars.<br>
880+
<code>{string{2..5}}</code> a string that has min. 2 chars and max 5 chars.<br>
881+
<code>{number{100-999}}</code> a number between 100 and 999.<br>
882+
</td>
883+
</tr>
884+
<tr>
885+
<td class="code">{type=allowedValues}<span class="label label-optional">optional</span></td>
886+
<td>
887+
Information about allowed values of the variable.<br>
888+
<code>{string="small"}</code> a string that can only contain the word "small" (a constant).<br>
889+
<code>{string="small","huge"}</code> a string that can contain the words "small" or "huge".<br>
890+
<code>{number=1,2,3,99}</code> a number with allowed values of 1, 2, 3 and 99.<br>
891+
<br>
892+
Can be combined with size:<br>
893+
<code>{string {..5}="small","huge"}</code> a string that has max 5 chars and only contain the words "small" or "huge".<br>
894+
</td>
895+
</tr>
896+
<tr>
897+
<td class="code">field</td>
898+
<td>
899+
Fieldname.
900+
</td>
901+
</tr>
902+
<tr>
903+
<td class="code">[field]</td>
904+
<td>
905+
Fieldname with brackets define the Variable as optional.
906+
</td>
907+
</tr>
908+
<tr>
909+
<td class="code">field[nestedField]</td>
910+
<td>
911+
Mandatory nested field.
912+
</td>
913+
</tr>
914+
<tr>
915+
<td class="code">=defaultValue<span class="label label-optional">optional</span></td>
916+
<td>
917+
The parameters default value.
918+
</td>
919+
</tr>
920+
<tr>
921+
<td class="code">description<span class="label label-optional">optional</span></td>
922+
<td>
923+
Description of the field.
924+
</td>
925+
</tr>
926+
</tbody>
927+
</table>
928+
929+
<p>Examples:</p>
930+
<pre class="example"><code>/**
931+
* @api {get} /user/:id
932+
* @apiParam {Number} id Users unique ID.
933+
*/
934+
935+
/**
936+
* @api {post} /user/
937+
* @apiParam {String} [firstname] Optional Firstname of the User.
938+
* @apiParam {String} lastname Mandatory Lastname.
939+
* @apiParam {String} country="DE" Mandatory with default value "DE".
940+
* @apiParam {Number} [age=18] Optional Age with default 18.
941+
*
942+
* @apiParam (Login) {String} pass Only logged in users can post this.
943+
* In generated documentation a separate
944+
* "Login" Block will be generated.
945+
*
946+
* @apiParam {Object} [address] Optional nested address object.
947+
* @apiParam {String} [address[street]] Optional street and number.
948+
* @apiParam {String} [address[zip]] Optional zip code.
949+
* @apiParam {String} [address[city]] Optional city.
950+
*/</code></pre>
951+
</article>
952+
853953
<!-- ============================================================ -->
854954

855955
<article id="param-api-define">
@@ -1554,6 +1654,89 @@ <h2>@apiPrivate</h2>
15541654
*/</code></pre>
15551655
</article>
15561656

1657+
<!-- ============================================================ -->
1658+
1659+
<article id="param-api-query">
1660+
<h2>@apiBody</h2>
1661+
<pre><code>@apiQuery [{type}] [field=defaultValue] [description]</code></pre>
1662+
<p>Describe a query parameter passed to your API-Method.</p>
1663+
<p>Usage: <code>@apiQuery {Number} id Users unique ID.</code></p>
1664+
1665+
<table>
1666+
<thead>
1667+
<tr>
1668+
<th>Name</th>
1669+
<th>Description</th>
1670+
</tr>
1671+
</thead>
1672+
<tbody>
1673+
<tr>
1674+
<td class="code">{type}<span class="label label-optional">optional</span></td>
1675+
<td>
1676+
Parameter type, e.g. <code>{Boolean}</code>, <code>{Number}</code>, <code>{String}</code>, <code>{Object}</code>, <code>{String[]}</code> (array of strings), ...
1677+
</td>
1678+
</tr>
1679+
<tr>
1680+
<td class="code">{type{size}}<span class="label label-optional">optional</span></td>
1681+
<td>
1682+
Information about the size of the variable.<br>
1683+
<code>{string{..5}}</code> a string that has max 5 chars.<br>
1684+
<code>{string{2..5}}</code> a string that has min. 2 chars and max 5 chars.<br>
1685+
<code>{number{100-999}}</code> a number between 100 and 999.<br>
1686+
</td>
1687+
</tr>
1688+
<tr>
1689+
<td class="code">{type=allowedValues}<span class="label label-optional">optional</span></td>
1690+
<td>
1691+
Information about allowed values of the variable.<br>
1692+
<code>{string="small"}</code> a string that can only contain the word "small" (a constant).<br>
1693+
<code>{string="small","huge"}</code> a string that can contain the words "small" or "huge".<br>
1694+
<code>{number=1,2,3,99}</code> a number with allowed values of 1, 2, 3 and 99.<br>
1695+
<br>
1696+
Can be combined with size:<br>
1697+
<code>{string {..5}="small","huge"}</code> a string that has max 5 chars and only contain the words "small" or "huge".<br>
1698+
</td>
1699+
</tr>
1700+
<tr>
1701+
<td class="code">field</td>
1702+
<td>
1703+
Fieldname.
1704+
</td>
1705+
</tr>
1706+
<tr>
1707+
<td class="code">[field]</td>
1708+
<td>
1709+
Fieldname with brackets define the Variable as optional.
1710+
</td>
1711+
</tr>
1712+
<tr>
1713+
<td class="code">field[nestedField]</td>
1714+
<td>
1715+
Mandatory nested field.
1716+
</td>
1717+
</tr>
1718+
<tr>
1719+
<td class="code">=defaultValue<span class="label label-optional">optional</span></td>
1720+
<td>
1721+
The parameters default value.
1722+
</td>
1723+
</tr>
1724+
<tr>
1725+
<td class="code">description<span class="label label-optional">optional</span></td>
1726+
<td>
1727+
Description of the field.
1728+
</td>
1729+
</tr>
1730+
</tbody>
1731+
</table>
1732+
1733+
<p>Examples:</p>
1734+
<pre class="example"><code>/**
1735+
* @api {get} /user/:id
1736+
* @apiQuery admin
1737+
*/</code></pre>
1738+
</article>
1739+
15571740
<!-- ============================================================ -->
15581741

15591742
<article id="param-api-sample-request">

0 commit comments

Comments
 (0)