Search code examples
swaggernestjs

How to add responses links in swagger on nestjs?

I want to create a link from a users get/list method 'id' property to a users/{id} getById method, in OAS3 / nestjs.

Something like this example (under 'Defining Links'): https://swagger.io/docs/specification/links/

Ive found a 'links' properties in 'schema' object, but I cant set it properly. Ive searched really hard for explicit definitions about how to set and work with this feature, but seemingly there's no much info about this neither in nestjs official documentation nor other resources.

Ive tried to do some variations of this:

  @ApiResponse({
    status: 200,
    description: 'Finds a user by id.',
    schema: { allOf: [{ $ref: getSchemaPath(UserModel) }] },
    links: {
      operationId: { $ref: 'list' },
    },
  })

But none of the sets Ive tried to pass under 'links' actually works; it just creates empty links fields in swagger UI.

Solution

  • This is poorly documented on NestJS's documentation and I had the same issue, but by going through Swagger's official documentation on Links as well as the @nestjs/swagger's source code, I figured the following works:

    @ApiResponse({
    description:
      "...",
    links: {
      'Link Name': {
        description: 'Some description',
        operationId: 'getUser',
        parameters: { userId: '$response.body#/userId' },
      },
    },
  })

    This should work and your result in Swagger UI should look like: enter image description here