vmarchaud / jsdoc-http-plugin Goto Github PK

View Code? Open in Web Editor NEW

40.0 40.0 10.0 30 KB

Document your http endpoints with JSDoc

License: MIT License

JavaScript 100.00%

documentation jsdoc nodejs tool

jsdoc-http-plugin's People

Contributors

Stargazers

Watchers

Forkers

ertrzyiks antonin-lebrard garnicio josudoey omgimalexis bitluck unitech alexander-girsh marudhupandiyang

jsdoc-http-plugin's Issues

Difference between the parameters & route params

Both show, one with no Type

/**
 * @function remove
 * @name remove
 * @description blah blah
 * @path {DELETE} /abc/:id
 * @params {string} id Unique identifier
 * @header {string} Authorization JWT token
 * @header {string} Content-Type application/json
 * @auth restrictToRoles('superadmin')
 * @code {200} If the request is successful
 * @code {500} Issue with blah blah
 * @since 1.0.0
 * @response {Json} response In {@link Json} format
 * @response {Object} response.data Empty object
 */

Not sure if I'm doing something wrong

Add escaping for parameter type

Bug with displaying array types, like:

@body {string[]} body_string_params - Array of string params     
@body {Object[]} body_object_params - Array of object params

When an array is passed as a type, the angle brackets are perceived as part of the HTML document. In HTML, it looks like:

<td class="type">
  Array.
  <object></object>
</td>

Actual result:

Expected result:

@param

the @param tag is already use by jsdoc and the addition of your plugin replace the name of @param for method.

Params Not Being Documented for Express Endpoints

Having an issue when @params are not showing in the following Express code:

/** Get object by ID endpoint
 * 
 * @name Fields by ID
 * @memberof Field APIs
 * @path {GET} /fields/:objectId
 * @params {String} :objectId is the Field ID to search by
 */
router.get('/:objectId', (req, res, next) => {
  fieldsSvc.getItem(req.params.objectId, 'Fields').then((data) => {
    res.json(data);
  }).catch(next);
});

I tried removing the namespace to see if it was affecting it but no change.

The route description + params is showing in doc generated where it is not supposed to

The route parameters table is showing, but the jsdoc comment for this function is :
/**
* @param {string} param1
* @param {string} param2
* @param {cb} callback
*/
function functionExample (param1, param2, callback) { }

So there is a problem.
I think I fixed it whith #7

Suppress default params table for a function

I have a following code piece documented.

 /**
     * Requires `customerOrderId` and `role` parameters.
     * @path {PUT} /eta/update/:customerOrder/:role
     * @params :customerOrderId
     * @params :role
     */
    static async updateTimer(req, res)

I really like the output of parameters related to HTTP routing. However, I would like to suppress the parameters section, which is in fact not relevant to the function signature. Is there such an option?

This plugin is very useful!

/**
 * A connection
 * @typedef {Object} Connection
 * @property {String} address IP address
 * @property {String} description Description
 * @property {String} interface Interface
 * @property {String} name Name
 * @property {String} netmask Netmask
 * @property {String} status Status
 * @property {String} type Type (WIFI/ETH)
 * @property {boolean} [captive] Enabled captive portal
 * @property {boolean} [dhcp_enabled] DHCP Enabled
 * @property {Number} [dhcp_lease] DHCP Lease (in seconds)
 * @property {String} [dhcp_range_end] DHCP range end
 * @property {String} [dhcp_range_start] DHCP range start
 * @property {Number} [vlan_id] Vlan ID
 * @property {String} [wifi_broadcast] Wifi Broadcast
 * @property {String} [wifi_key] Wifi security key
 * @property {String} [wifi_security] Wifi security
 * @property {String} [wifi_ssid] Wifi SSID
 */

I would to use it as the @Body in a jsdoc for my create function:

/**
 * @function create
 * @name create
 * @description Create a connection
 * @path {POST} /connection
 * @header {String} Authorization JWT token
 * @header {String} Content-Type application/json
 * @auth No roles / permissions required
 * @body {Connection} Connection In {@link Connection} format
 * @code {200} If the request is successful
 * @code {500} IP Address is not valid
 * @code {500} IP host address XYZ cannot be 0 or 255
 * @since 1.0.0
 * @response {myJson} response
 * @response {Object} response.data Connection created
 */

Any ideas please as its not outputting in the generated html.

Thanks
Sharry

add code columns to response

Hy,
first time i post an isssue sorry if this doesn't gone here :/
I wan't to know if it's possible to add the 'http response code' columns into the response.

exemple:
name|tpye|description|code

by the way thank for the @response and @code :)

vmarchaud / jsdoc-http-plugin Goto Github PK

jsdoc-http-plugin's People

Contributors

Stargazers

Watchers

Forkers

jsdoc-http-plugin's Issues

Difference between the parameters & route params

Add escaping for parameter type

@param

Params Not Being Documented for Express Endpoints

The route description + params is showing in doc generated where it is not supposed to

Suppress default params table for a function

Get a directory=<directory> is mandatory

Undefined when description is missing

Use of @typedef in @body

add code columns to response

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent