如何在NestJS（OAS3）的Swagger中添加接口响应关联链接？

要实现用户列表接口返回的id与详情接口的关联跳转，得按OAS3规范正确配置links，以下是可行的实现步骤：

1. 给详情接口指定唯一的operationId #

首先得给用户详情接口（users/{id}）设置明确的operationId，因为列表接口的links需要通过这个ID关联到详情接口：

@Get(':id')
@ApiOperation({ operationId: 'getUserById' }) // 关键：指定唯一operationId
@ApiResponse({
  status: 200,
  type: UserModel,
  description: '获取用户详情'
})
async getUserById(@Param('id') id: string) {
  // 业务逻辑：根据id查询用户
  return this.userService.findById(id);
}

2. 在列表接口的响应中配置links #

在用户列表接口（users）的@ApiResponse里，按照OAS3的Link对象规范配置links，重点是指定参数映射关系：

@Get()
@ApiOperation({ operationId: 'getUserList' })
@ApiResponse({
  status: 200,
  type: [UserModel], // 指定返回数组类型为UserModel
  description: '获取用户列表',
  links: {
    // 自定义链接名称，比如"查看用户详情"
    查看用户详情: {
      operationId: 'getUserById', // 关联到详情接口的operationId
      parameters: {
        // JSON Pointer：从响应体的每个数组元素中取id，作为详情接口的path参数
        id: '$response.body#/[*]/id'
      },
      description: '点击查看该用户的详细信息'
    }
  }
})
async getUserList() {
  // 业务逻辑：查询用户列表
  return this.userService.findAll();
}

关键注意事项 #

• JSON Pointer格式：$response.body#/[*]/id 是OAS3规定的语法，[*]表示匹配响应数组中的每一个元素，id对应元素的id字段，这个值会自动填充到详情接口的{id}路径参数中。
• UserModel的Schema配置：确保UserModel类用@ApiProperty装饰了id字段，这样Swagger才能正确识别字段：

  export class UserModel {
    @ApiProperty({ description: '用户ID' })
    id: string;
  
    @ApiProperty({ description: '用户名' })
    username: string;
  
    // 其他字段...
  }
  

• 避免错误配置：你之前的写法错误在于links的结构不符合规范，OAS3的links是键值对，每个键对应一个完整的Link对象（包含operationId、parameters、description等），而不是直接引用operationId。

这样配置后，在Swagger UI中查看用户列表接口的响应时，每个用户条目旁会出现你配置的链接，点击就能跳转到对应的详情接口并自动填充id参数。

内容的提问来源于stack exchange，提问作者Yuri Silva