Example or Docs required to explain how to specify params?

[oespn]

Discussed in https://github.com/jellydn/next-swagger-doc/discussions/527

^{Originally posted by oespn November 3, 2022}
I'm playing with a trivial example where there is a single param of the 'id' of the person.

If I use the path template in the open api spec v3 https://swagger.io/docs/specification/paths-and-operations/ the swagger docs won't generate.

*     parameters:
*       - in: path
*         name: id
*         type: integer
*         required: true
*         description: Numeric ID of the person to get.

I've fiddled a little and can get the {id} to appear in the path but do not know how to have the lib identify the params and create the relevant front-end control or even list the name, description, type of the param.

here's my code:

/**
 * @swagger
 * /api/people/{id}:
 *   get:
 *     description: Returns the person matching Id
 *     parameters:
 *         name: id
 *         description: Numeric ID of the person to get.
 *     responses:
 *       200:
 *         description: data of Id 
 *       404: 
 *         description: Id not found.
 */
export default function personHandler(
  req: NextApiRequest,
  res: NextApiResponse<Person | ResponseError>
) {
  const { query } = req
  const { id } = query
  const filtered = people.filter((p) => p.id === id)

  // User with id exists
  return filtered.length > 0
    ? res.status(200).json(filtered[0])
    : res.status(404).json({ message: `User with id: ${id} not found.` })
}

Is the lib able to handle parameters? If so, how?

[jellydn]

Hi there. You. could take a look at the swagger-jsdoc's example https://github.com/Surnet/swagger-jsdoc/blob/v6/examples/app/routes.js Hopefully that would help you on this. Thanks.

[oespn]

I see. From your suggestion I looked for other repos with examples using the jsdoc lib and found this one which is more like my case.
https://github.com/Wil-g2/swaggerExample/blob/master/index.js
ie. a single parameter

 *     parameters:
 *     - in: path
 *       name: ac_id
 *       schema:
 *         type: string
 *       required: true
 * 

In the end, the solution for me was to pay attention to the spacing in the indentations. I'm a 'tab' indenter... I found I need to clear all tabs and single space all the swagger meta data.

Thanks for your help and for the lib!

[jellydn]

In the end, the solution for me was to pay attention to the spacing in the indentations. I'm a 'tab' indenter... I found I need to clear all tabs and single space all the swagger meta data.

You're right. That's NOT easy to spoil the issue with tab or spaces :)