typescript - Hur definierar man svarskroppsobjektet i ett NestJs-genererat Swagger-dokument?

Jag använder NestJs och dess Swagger-plugin för att automatiskt generera dokumentation för mitt API.

Problemet är att jag inte kan lista ut hur jag får response-schemat att visas i dokumentationen. I mina GET-rutter får jag bara "Kod 200", utan någon datastruktur.

Jag har en typisk uppsättning, där en kontrollmetod använder en motsvarande tjänstemetod, som i sin tur använder ett TypeOrm-repository. Till exempel:

@Get()
 findAll() {    
   return this.usersService.findAll();
}

Jag försökte använda @ApiResponse-dekorationen, men såg egentligen inget sätt att få den att fylla detta syfte. Dessutom gjorde det ingen nytta att skapa en user.dto.ts och göra den till returtyp för controller-routen.

Till slut är detta vad jag får i Swagger:

Hur kan jag definiera svarskroppens schema?

Svar #1

Du kan använda type och isArray egenskaper tillsammans med ApiResponse-familjen av dekoratörer. Till exempel:

@ApiOkResponse({
    description: 'The user records',
    type: User,
    isArray: true
})
@Get()
 findAll() {    
   return this.usersService.findAll();
}

Dessutom bör du överväga att använda Swagger CLI-pluginet för att hjälpa dig att få dessa dekoratorer tillämpade automatiskt under byggtiden istället för att du måste hålla allt synkroniserat manuellt.

Svar #2

Du kan kommentera kontrolleråtgärden med ApiExtraModels:

import { ApiExtraModels, ApiResponse, getSchemaPath } from '@nestjs/swagger'
import { Controller, Get, Param } from '@nestjs/common';

@Controller('users')
export class UsersController {


 @ApiExtraModels(UserDto)
 @ApiResponse({
    status: 200,
    schema: {
      $ref: getSchemaPath(UserDto),
    },
  })
  @Get('/:userId')
  getById(@Param('userId') userId: string): UserDto {
     ... something happens ... 
     return myUserDto;
  }

}

och du måste också annotera UserDto-egenskaper med ApiProperty:

import { ApiProperty } from '@nestjs/swagger'
import { Expose } from 'class-transformer'
import { IsString } from 'class-validator'

export class UserDto {

  @ApiProperty()
  @IsString()
  @Expose()
  id: string;
}

Förresten, kolla in CLI-pluginen för att generera ApiProperty

Relaterade artiklar