Question about using the object notation for @property about express-jsdoc-swagger HOT 2 CLOSED

Hello, @NolanChan,

You can specify the structure of objects by using @typedef to define schemas, such as this example in the documentation:

/**
 * A song type
 * @typedef {object} Song
 * @property {string} title.required
 * @property {string} artist
 * @property {number} year
 */

As you can see here, Song will be an object, and you can use @property to define the different properties an instance of Song can have.

If you want to tell the library that your endpoint is going to return an object with this structure, you can just assign it the type Song after having defined the type with @typedef, as in the example above.

/**
 * GET /api/v1/song/:songId
 * @return {Song} 200 - success response - application/json
 */

If you want to define the structure of an object property inside of an existing schema, the procedure would be the same: you'll have to define a model with the structure your property is supposed to have. The following is an example of a Song object with an artist property that will be an object with two fields: name and age.

/**
 * @typedef {object} Artist
 * @property {string} name.required
 * @property {number} age
 */

/**
 * @typedef {object} Song
 * @property {string} title.required
 * @property {Artist} artist
 * @property {number} year
 */

Hope that helps! 🙂

from express-jsdoc-swagger.

I'm closing this due to inactivity @NolanChan feel free to re-open in case your problem was not solved with the previous comment 👍

from express-jsdoc-swagger.