Skip to content
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.

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

@apiBody support #3

Open
JMLX42 opened this issue Apr 2, 2023 · 1 comment
Open

@apiBody support #3

JMLX42 opened this issue Apr 2, 2023 · 1 comment

Comments

@JMLX42
Copy link

JMLX42 commented Apr 2, 2023

Hello,

Thank you for the great work!

While attempting to generate our swagger.json, I came across a problem.
AFAIK, apidoc's idiomatic way to document API request body parameters is using the @apiBody instruction:

https://apidocjs.com/#param-api-body

Using @apiBody actually throws the following warning:

{"level":"warn","message":"parser plugin 'apibody' not found in block: 0 in file: app/router.js"}

And the corresponding swagger.json is missing those parameters entirely.

Any specific reason why it is implemented as @apiParam (Body) here instead?

As a corollary, IMHO @apiParam (Query) should simply be @apiParam.

@JMLX42
Copy link
Author

JMLX42 commented Apr 6, 2023

Just to make sure I am 100% clear, this is what the README example should look like IMHO:

/**
* @api {post} /test_api desc_test_api
* @apiName test_api_name
* @apiGroup search
*
* @apiHeader {String} [taz] desc_taz
*
* @apiParam {Number} [tar] desc_tar
* @apiParam {String} bar=bar desc_bar
* @apiBody {Object[]} foo desc_foo
* @apiBody {String} foo.foz desc_foo.foz
*
* @apiParamExample {json} request_desc
* {{extraExample}}
*
* @apiSuccess {Number} [code=1] desc_override_code
* @apiSuccess {Object} data data_desc
* @apiSuccess {number} data.keyInDoc desc_add_extra_data_key_in_doc
*
* @apiSuccessExample {json} response_desc
* HTTP/1.1 200 OK
*  {
   "code": 200,
    "data": {
        "keyInExample": 1
  }
}
*
* @apiSuccessExample {json} error_desc
* HTTP/1.1 300 OK
* {{fooInJs:barInJs}}
*/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant