BRIKEV / express-jsdoc-swagger

Swagger OpenAPI 3.x generator
https://brikev.github.io/express-jsdoc-swagger-docs/#/
MIT License
219 stars 30 forks source link

Syntax for specifying JSON object fields and nested objects in one place #212

Open ciprian1234 opened 2 years ago

ciprian1234 commented 2 years ago

Currently I believe if we want to specify JSON body fields of a POST/PUT request we need to create a separate object with @typedef keyword. Its would be nice to support following syntax.

/**
 * POST /item
 * @summary Create item
 * @param {object} request.body.required - object info
 * @param {string} request.body.field1.required - field1 info (required)
 * @param {string} request.body.field2 - field2 info
 * @param {object} request.body.field3.required - field3 info (required)
 * @param {string} request.body.field3.subfield1 - field3.subfield1 info
 * @param {string} request.body.field3.subfield2.required - field3.subfield2 info (required)
 *
 */

So in this case the POST /item endpoint should expect an object like this

{
  field1: 'data', // required field  
  field2: 'data',  
  field3: {  
    subfield1: 'data',  
    subfield2: 'data', // required field  
  },  
};
wbw20 commented 2 years ago

I agree this is a big missing feature right now. As it stands now, any large-ish API's docs will be bloated with typedefs of the request bodies. Specifying them inline would fix the issue.

sjmunoz commented 1 year ago

Any update on this?

madilekci-avena commented 8 months ago

Upvote. I also came here to open an issue like this