How can we set parameter `description` and `example`?

Is it currently not possible to set the parameter description and example?

From what I can tell the parameter fields supported are:

• in
• name
• required
• schema

I’d be interested in contributing if you have an idea in mind how we can support setting a default description and example.

https://swagger.io/specification/#parameterObject

[lokesh1197]

There’s no place to define description and example out of the box, that’s correct. Couple of ways around this come to mind:

using QueryParams/Params etc instead of QueryParam/Param:

class MyQueryParams {
  @JSONSchema({ description: 'my ID query parameter' })
  @IsString()
  id: string
}

someHandler(@QueryParams() queryParams: MyQueryParams) {
    // ...
}

my ID query parameter description then ends up in the parameters[0].schema object. We’re missing handling for @Params right now so that would need to be added.

adding another decorator , something along the lines of:

function OpenAPIParam(name: string, props: Partial<ParameterObject>) {
  return OpenAPI(schema => {
    const index = schema.parameters.findIndex(
      p => 'name' in p && p.name === name
    )
    if (index > -1) {
      schema.parameters[index] = {
        ...schema.parameters[index],
        ...props
      }
    }
    return schema
  })
}

@OpenAPIParam('id', { description: 'My ID path parameter', example: 1234 })
someHandler(@Param('id') id: number) {
  // ...
}

Now description ends up in parameters[0] - not inside schema like above.

The second example if very helpful and I think most users might need it. Wouldn’t it be great to add it to the package?

[epiphone]

There’s no place to define description and example out of the box, that’s correct. Couple of ways around this come to mind:

using QueryParams/Params etc instead of QueryParam/Param:

class MyQueryParams {
  @JSONSchema({ description: 'my ID query parameter' })
  @IsString()
  id: string
}

someHandler(@QueryParams() queryParams: MyQueryParams) {
    // ...
}

my ID query parameter description then ends up in the parameters[0].schema object. We’re missing handling for @Params right now so that would need to be added.

adding another decorator , something along the lines of:

function OpenAPIParam(name: string, props: Partial<ParameterObject>) {
  return OpenAPI(schema => {
    const index = schema.parameters.findIndex(
      p => 'name' in p && p.name === name
    )
    if (index > -1) {
      schema.parameters[index] = {
        ...schema.parameters[index],
        ...props
      }
    }
    return schema
  })
}

@OpenAPIParam('id', { description: 'My ID path parameter', example: 1234 })
someHandler(@Param('id') id: number) {
  // ...
}

Now description ends up in parameters[0] - not inside schema like above.