【NestJS】NestJSでOpenAPI（Swagger）形式で出力

概要

NestJSではOpenAPI（Swagger）形式でAPIドキュメントを出力できます。以下のドキュメントを参考に設定をしていけばドキュメント出力が可能です。

docs.nestjs.com

OpenAPIに出力したい内容がデコレータで定義できるので、APIドキュメントと実際のAPIの差が無くなりやすくなります。

設定方法

@nestjs/swagger と swagger-ui-express をパッケージに追加。
SwaggerModule と DocumentBuilder を使用してAPIドキュメントの出力設定をする。
ApiModelProperty デコレータなどを使用してAPIに出力する内容を記載していく。

サンプル

実行環境

Node.js - 10.x
Yarn - 1.13.x

使用ライブラリ

@nestjs/common - 6.0.x
@nestjs/core - 6.0.x
@nestjs/platform-express - 6.0.x
@nestjs/swagger - 3.0.x
swagger-ui-express - 4.0.x
typescript - 3.2.x

src/main.ts

import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

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

  // Swagger用の定義を設定
  const options = new DocumentBuilder()
    .setTitle('Swagger example')
    .setDescription('The API description')
    .setVersion('1.0')
    .addTag('test')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);

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

src/app.module.ts

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

src/dto.ts

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

export class HogeDto {
  @ApiModelProperty({ description: 'id' })
  id: string;

  @ApiModelProperty()
  name: string;
}

src/app.controller.ts

import { Controller, Get, Param } from '@nestjs/common';
import { ApiResponse, ApiUseTags } from '@nestjs/swagger';
import { HogeDto } from './dto';

@ApiUseTags('sample')
@Controller()
export class AppController {
  @Get('hoge/:id')
  @ApiResponse({ status: 200, type: HogeDto })
  findOne(@Param('id') id: string): HogeDto {
    return {
      id,
      name: 'aaa',
    } as HogeDto;
}