0

This is my first use of apiDocs and I'm following exactly the documentation provided. The issue is that I'm defining the apiName and apiGroup but only apiGroup is shown in the output. This is my definition:

/**
 * @apiVersion 1.0.0
 * @api {post} /users/register
 * @apiGroup users
 * @apiName register
 * @apiDescription Register new user
 * @apiParam {String} userName User email address
 * @apiParam {String} passWord User password
 * @apiSuccess {json} response error, message
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "error": false,
 *       "message": "USER_CREATED_SUCCESSFULLY"
 *     } 
 * @apiError {json} error error, message
 * @apiErrorExample {json} Error-USER_CREATE_FAILED:
 *     HTTP/1.1 200 Error creating user
 *     {
 *       "error": true
 *      ,"message" : "USER_CREATE_FAILED"
 *     }
 */

This is my apidoc.json:

{
  "name": "T-Rex",
  "version": "1.0.0",
  "description": "API Document",
  "title": "T-Rex",
  "url": "https://apiusr.t-rex.io",
  "template": {
       "withCompare": true,
       "withGenerator": true
     }
}

But the output list just the group name, ignoring the apiName:

users //apiGroup, it's ok

users //Should be @apiName, but showing the group

Delete user device association //@apiDescription, ok

The rest of the output is fine.

GIJOW
  • 2,307
  • 1
  • 17
  • 37

1 Answers1

4

I think I found how it works! Try with this:

/**
 * @apiVersion 1.0.0
 * @api {post} /users/register Register
 * @apiGroup users
 * @apiName PostRegister

Basically the @api keyword has three parameters:

  1. the HTTP method (post)
  2. the API route (/users/register)
  3. the name of the route (Register)

Then in the @apiName you need to specify a unique reference for that route that is then inserted in the html code and, following the doc, it would be better if starts with the HTTP method name.

matteomattei
  • 650
  • 5
  • 9
  • `@api {post} /users/register Register` is working as expected. But I don't see `@apiName` rendered anywhere. It just seems useless. – srx Feb 21 '20 at 19:55
  • 1
    @srx It is inserted into the HTML code as a link anchor name, so in the OP example the link will be `index.html#api-users-PostRegister`. – zippycoder Apr 18 '21 at 20:39