Providing an example value for the request body doesn't seem possible...?

[gkpo]

Sorting

• I'm submitting a ...

  • [ ] bug report
  • [x] feature request
  • [ ] support request

• I confirm that I

  • [x] used the search to make sure that a similar issue hasn't already been submit

Expected Behavior

I expected to be able to provide example values for the input of a POST endpoint using the @Example decorator in TSOA. Specifically, I want to define an example for a body parameter, and have it appear in the generated Swagger/OpenAPI documentation.

What I tried

@Post()
@Security("api_key_and_user_id")
@Example<Journey>(JourneyResponseExample)
public async createJourney(
  @Request() request: express.Request,
  @Body() @Example<CreateJourneyRequest>({ // <-------- This is the bit i'd like to see reflected in the generated doc
    city: "Paris",
    categoryNames: ["Food"],
    from: 8,
    to: 23,
    price: [0, 1, 2, 3],
    lat: 48.856614,
    lng: 2.3522219,
    radius: 2
  }) body: CreateJourneyRequest
): Promise<Journey> {
  // ... rest of the method implementation
}

Current Behavior

The documentation is not including my example. Value. It does provide random values inferred from the CreateJourneyRequest type though:

// This is what I actually see generated in Swagger:
{
  "city": "string",
  "categoryNames": [
    "string"
  ],
  "from": 0,
  "to": 0,
  "price": [
    0
  ],
  "lat": 0,
  "lng": 0,
  "radius": 0
}

[github-actions[bot]]

Hello there gkpo 👋

Thank you for opening your very first issue in this project.

We will try to get back to you as soon as we can.👀

[pquerner]

You may give examples in the function doc:

/**
* Explaining what the call does
*
* @param body
* @example body {
*    "foo": "bar"
* }
*/
@Post()
@Security("api_key_and_user_id")
@Example<Journey>(JourneyResponseExample)
public async createJourney(
  @Request() request: express.Request,
  @Body() @Example<CreateJourneyRequest>({ // <-------- This is the bit i'd like to see reflected in the generated doc
    city: "Paris",
    categoryNames: ["Food"],
    from: 8,
    to: 23,
    price: [0, 1, 2, 3],
    lat: 48.856614,
    lng: 2.3522219,
    radius: 2
  }) body: CreateJourneyRequest
): Promise<Journey> {
  // ... rest of the method implementation
}

If you have a required parameter (for instance in a GET route), you can do this:

/**
* Explain the call
* @param yourParam
* @example yourParam "fooBar"
**/

See the docs here: https://tsoa-community.github.io/docs/examples.html

[github-actions[bot]]

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