Closed pablo-redradix closed 11 months ago
Hello there pablo-redradix 👋
Thank you for opening your very first issue in this project.
We will try to get back to you as soon as we can.👀
I think I found the culprit: in parameterGenerator.ts
you can find this:
const { examples: example, exampleLabels } = this.getParameterExample(parameter, parameterName);
It merely renames destructured examples
to example
, but it's still an array. This does the trick:
const { examples, exampleLabels } = this.getParameterExample(parameter, parameterName);
const example = examples?.length ? examples[0] : undefined
This line can be found five times in said file, once per property type allowing for a single example
Shouldn't they have labels, even if they're just called example-{n}? I'd prefer if we used examples for oas 3
Swagger spec doesn't allow for labels in param examples:
parameters:
- in: query
name: status
schema:
type: string
enum: [approved, pending, closed, new]
example: approved #Example of a parameter value
Link to Swagger docs
It would be great if tsoa had an option to add request examples (maybe through a parameter in @Example
decorator, or even a new @RequestExample
decorator), but that belongs in a feature request. This thread is about fixing a bug.
I was thinking:
parameters:
- in: query
name: status
schema:
type: string
enum: [approved, pending, closed, new]
examples: # Multiple examples
example-0: # Distinct name
value: approved # Example value
That would be more consistent with previous work such as https://github.com/lukeautry/tsoa/pull/1168 and https://github.com/lukeautry/tsoa/pull/1275
How do you propose multiple parameter examples be handled?
/**
* @example stringParam "First example for stringParam"
* @example stringParam "Second example for stringParam"
* @example numberParam 4815162342
*/
@Post('test')
public async testMethod(
@BodyProp() stringParam: string,
@BodyProp() numberParam: number,
@BodyProp() thirdParam: boolean
) {
return
}
That's a valid annotation that doesn't map well to your proposed solution: parameters can each have 0..N examples. Swagger allows for two distinct forms of input examples:
example
(ignoring subsequent ones seems reasonable)examples
As of today, tsoa has zero support for the latter, and erroneous support for the former. It is my understanding that both should be addressed: the first one via bug fix (such as this ticket's), the second one via a new feature that allows for full-input use of the @Example
decorator:
Maybe the @Example
decorator could take a third optional object parameter like this:
@Example<MyInputInterface>({
stringParam: "First example for stringParam",
numberParam: 1,
thirdParam: true
}, 'Example 1', { isInputExample: true })
@Example<MyInputInterface>({
stringParam: "Second example for stringParam",
numberParam: 2,
thirdParam: false
}, 'Example 2', { isInputExample: true })
@Post('test')
public async testMethod(
@BodyProp() stringParam: string,
@BodyProp() numberParam: number,
@BodyProp() thirdParam: boolean
) {
return
}
Please note that this solution does not address the buggy implementation of per-parameter jsdoc annotation of examples. That's why I think this belongs in a separate feature request ticket.
This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days
Sorting
I'm submitting a ...
I confirm that I
Expected Behavior
Examples for scalar parameters should remain scalar:
Current Behavior
Instead, they are made into single-element arrays:
Steps to Reproduce
Context (Environment)
Version of the library: Tried with versions 5 and 6-rc Version of NodeJS: 18.16.1