diff --git a/docs/describing-parameters.md b/docs/describing-parameters.md index 497fa54..7080cc5 100644 --- a/docs/describing-parameters.md +++ b/docs/describing-parameters.md @@ -133,6 +133,16 @@ Assuming `offset` defaults to 0 and `limit` defaults to 20, you would define the */ ``` +### Example parameter values +Append `e.g. value` to the end of the description to define an example value for the parameter. +This is useful for required parameters that you want to provide an example value. + +```js +/** + * @queryParam {integer} id - The user id to search for. e.g. 20 + */ +``` + ### Enum parameters You can restrict a parameter to a fixed set of values by adding the `enum` to the `schema`. The enum values must be of the same type as the parameter data type. diff --git a/src/util/commentsToOpenApi.ts b/src/util/commentsToOpenApi.ts index de462a4..1d50e13 100644 --- a/src/util/commentsToOpenApi.ts +++ b/src/util/commentsToOpenApi.ts @@ -92,10 +92,12 @@ function parseDescription(tag: any) { items: { ...rootType, }, + example: undefined }; } else { schema = { ...rootType, + example: undefined }; } @@ -103,9 +105,16 @@ function parseDescription(tag: any) { schema = undefined; } + // Get the example value from end of the description + const desc = tag.description.trim().split('e.g.') + if (desc[1] && schema) { + schema.example = desc[1].trim() + } + + // remove the optional dash from the description. - let description = tag.description.trim().replace(/^- /, ''); - if (description === '') { + let description = desc[0].trim().replace(/^- /, ''); + if (description === '' || description === '-') { description = undefined; }