Apidoc: Elixir apiDoc comments not being picked up, "Nothing to do"

Created on 16 Nov 2018 · 4Comments · Source: apidoc/apidoc

On macOS, inside a Phoenix 1.4/Elixir project, I have commented my apiDoc markup like so in my router.ex, with and without space between the first and last characters(e.g. #{, #} and # {, # }).

  # {
  # @api {post} api/admin/login Log in a user
  # @apiName LogIn
  # @apiGroup User
  #
  # @apiParam {String} email User's unique email.
  # @apiParam {String} password User's password.
  #
  # @apiSuccess {String} jwt JSON Web Token encoded with user resource.
  # }

    post "/login", UserController, :login

Running apidoc -i lib/ -o apiDocs/ returns {"message":"Nothing to do.","level":"info"}

Passing --debug , I get:

{"message":"inspect file: lib/json_api_web/router.ex","level":"debug"}
{"message":"size: 1990","level":"debug"}
...
{"message":"Nothing to do.","level":"info"}

and no errors.

I am assuming there is something wrong with my comment syntax/the Elixir syntax referenced in the official docs?

The above apiDoc markup runs when put in JS format in a .js file

Source

njwest

Most helpful comment

Official doc is wrong. This worked for me:

        @apidoc """
        @api {post} /server/:server_cid/log/ Create new log
        @apiVersion 2.0.0

        @apiDescription Starts a LogForgeProcess with ForgeCreate action. Once
        completed, a brand new fake log will be created.

        @apiName LogForgeCreate
        @apiGroup Log

        @apiParam {LogType} log_type Type of the desired log.
        @apiParam {LogData} log_data Contents of the desired log.
        """

renatomassaro on 25 Nov 2018

👍3 🎉1

All 4 comments

Official doc is wrong. This worked for me:

        @apidoc """
        @api {post} /server/:server_cid/log/ Create new log
        @apiVersion 2.0.0

        @apiDescription Starts a LogForgeProcess with ForgeCreate action. Once
        completed, a brand new fake log will be created.

        @apiName LogForgeCreate
        @apiGroup Log

        @apiParam {LogType} log_type Type of the desired log.
        @apiParam {LogData} log_data Contents of the desired log.
        """

renatomassaro on 25 Nov 2018

👍3 🎉1

but it doesn't work in my project. i have a file named 'apidoc.json' in my project
and i add this to one class
`
class Account(tornado.web.RquestHandler):
'''
@apidoc
@api {get} /account Reuquest User Information
@apiVersion 0.1.0
@apiName Account
@apiGroup User
@apiPermission level_1_or_2
@apiDescription API of Account
@apiExample Get:
{
'msg': 'ok'
}
@apiParam {String} username unique ID
@apiSuccess {String} success status of the request
@apiSuccess {json} Success-Response:
HTTP/1.1 200 OK
{
'success': True,
'data': {}
}
@apiErrorExample {json} Error-Response:
HTTP/1.1 404 Not Found
{
'success': False,
'msg': '---'
}