NestJS의 @nestjs/swagger에서 컨트롤러로부터 Open API(Swagger)를 생성하는 정의서

이 글은 NestJS Advent Calendar 2019의 16일째 글입니다.

입문

이 글은 모듈@nestjs/swagger을 소개했다.이 모듈을 사용하면 NestJS 컨트롤러 구현에 디코더를 추가하여 Open API(Swagger) 사양 설명서를 생성할 수 있습니다.'JSON/YAML에서 API를 정의할 필요가 없다','코드와 API 규범을 실현하는 데 더 이상 어긋나지 않는다'는 장점이 있다.
본문@nestjs/swagger의 판본은 4.0.9로 가정한다.이 4계는 12월 초에 발표되었는데 OpenAPI3.0을 지원하는 것 외에 파괴적인 변화도 있었다.3 계열과 다른 부분이 몇 개 생겼기 때문에 기존 프로젝트에서 이미 가져온 사람은 주의하십시오.

샘플 저장소

@nestjs/swagger 배치

NestJS 프로젝트를 생성하고 설치@nestjs/swagger 및swagger-ui-express합니다.

$ npx -p @nestjs/cli nest new day15-swagger
$ yarn add @nestjs/swagger swagger-ui-express

사용@nestjs/swagger을 위해 다음과 같이main.ts 편집해.

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const options = new DocumentBuilder()
    .setTitle('NestJS アドベントカレンダーサンプル')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

yarn start:dev를 실행하고 http://localhost:3000/api/에 액세스하면 Swagger UI 페이지가 표시됩니다.
/ 단점만 표시되고 요청이나 응답은 표시되지 않습니다.다음에 주석을 사용하여 요청과 응답을 정의해 보십시오.

@nestjs/swagger의 API 정의 사용하기

여기에는 GET /items의 단점이 준비되어 있다.이 단점은 그룹에서 item의 id를 수신하고 그룹에서 실제 item을 되돌려줍니다.
우선, item의 모델을 정의합니다.
src/model/item.model.ts

import { ApiProperty } from '@nestjs/swagger';

export class Item {
    @ApiProperty()
    id: number;
    @ApiProperty()
    name: string;
}

그런 다음 이 item 모델을 사용하여 DTO를 정의합니다.@ApiProperty 주석@nestjs/swagger으로 이 속성은 패턴 생성의 대상임을 알려 줍니다.
src/dto/item.dto.ts

import { Item } from "src/model/item.model";
import { ApiProperty } from "@nestjs/swagger";

export class GetItemsResponse {
    @ApiProperty({ type: [Item] })
    items: Item[];
}

export class GetItemsRequest {
    @ApiProperty({ type: [Number] })
    ids: Item["id"][]
}

마지막으로 컨트롤러에 새 끝점을 추가합니다.
src/app.controller.ts

import { Controller, Get, HttpStatus, Query } from '@nestjs/common';
import { ApiResponse } from '@nestjs/swagger';
import { AppService } from './app.service';
import { GetItemsResponse, GetItemsRequest } from './dto/item.dto';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('/item')
  @ApiResponse({ status: HttpStatus.OK, type: GetItemsResponse })
  getItems(@Query() { ids }: GetItemsRequest): GetItemsResponse {
    return { items: [] };
  }

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }

}

아까와 같이 방문http://localhost:3000/api/.
디렉터에 구현 /items 요청 및 응답이 추가되었습니다.또한 모델이나 dto로 정의된 클래스도 Schemas에 추가됩니다.

oke 서버에 값 추가

지정@ApiProperty의 매개 변수example를 통해 OpenAPI 사양 설명서를 사용하는 Moke 서버의 응답을 정의할 수 있습니다.
src/dto/item.dto.ts

import { Item } from 'src/model/item.model';
import { ApiProperty } from '@nestjs/swagger';

export class GetItemsResponse {
    @ApiProperty({ type: [Item], example: [{ id: 1, name: 'test' }] })
    items: Item[];
}

export class GetItemsRequest {
    @ApiProperty({ type: [String], example: ['1', '2', '3'] })
    ids: string[];
}

Moke 서버를 만들어 보세요.설치@stoplight/prism-cli.

$ yarn add -D @stoplight/prism-cli

그리고 curl http://localhost:3000/api-json > spec.json 규격서의 json 파일을 다운로드합니다.
Moke 서버를 시작합니다.

$ yarn prism mock spec.json

요청을 하면 example 에 적힌 값이 응답으로 되돌아오는 것을 발견할 수 있습니다.

$ curl "http://127.0.0.1:4010/item?ids=1"
{"items":[{"id":1,"name":"test"}]}

끝날 때

사용@nestjs/swagger을 통해 컨트롤러의 정의와 OpenAPI의 정의를 동시에 생성할 수 있음을 소개했다.