Swagger

SwagerはNestJS公式サイトで紹介されているAPIドキュメント自動化ツールです.コラボレーションでは、「あるエンドポイントに入るには何らかの方法を使用し、bodyにこの値を加える」と説明する必要がある場合があります.Swagerを使うのはpptやコンセプトを使うより簡単です.
その利点は,コードを記述し,直ちに記述と修正を行い,APIをテストできることである.

Swaggerの取り付け

Express環境とfastify環境では、インストールするモジュールが異なります.expressを使用しているので、以下のモジュールをインストールしました.

npm install --save @nestjs/swagger swagger-ui-express

Swaggerを使用(1)

mainからSwaggerModuleクラスにSwaggerを初期化します.createDocument()メソッドを使用してAPIドキュメントを作成できます.configは、title、description、versionなどを設定できるオプションです.接続されたエンドポイントは、SwaggerModule.setup()メソッドによって設定されます.http://localhost:3000/docsにアクセスできます.

import { HttpExceptionFilter } from 'src/cats/commons/exceptions/http-exception.filter';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';
import { DocumentBuilder, OpenAPIObject, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  app.useGlobalFilters(new HttpExceptionFilter());

  const config = new DocumentBuilder()
    .setTitle('C.I.C')
    .setDescription('cat')
    .setVersion('1.0.0')
    .addTag('cats')
    .build();
  const document: OpenAPIObject = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document);
  
  ⁝ 
  (생략)
  

http://localhost:3000/docsに接続すると、Nestはコントローラを解析し、対応するAPIを解放します.
であるが、各APIが何を意味するかをすぐに知ることは難しい.APIに説明を追加するには、controllerが@ApiOperation decoratorを担当します.

 @ApiOperation({ summary: '회원가입' })
  @Post()
  async signUp(@Body() body: CatRequestDto) {
    // ‥ (생략)
 }

対応するAPIにsummaryを追加すると、Swagerは対応する説明を与えます.

Swagger(2)-Request Bodyの設定

SwagerはAPIテスト機能をサポートし、bodyに直接入力してテストすることができる.この場合、どのbodyを使用すべきか、どのオブジェクトを渡すべきかを示す別の設定が必要です.この設定は、DTO、CatRequestDto〜@ApiPropertyデコーダによって行うことができる.

@ApiProperty({
  example: '[email protected]',
  description: 'email',
  required: true,
})
// ‥ (생략)

要求体領域も火をつけている.

Swagger(3)-レスポンスの設定

これまで、APIへの説明、リクエストを送信する内容が設定されていた.最後の送信応答を設定する番になったときの結果値はどのように出力されますか.応答設定は、APIの説明を記述するときと同様にcontrollerによって完了します.
まず、ResponseDtoを作成するために、cat.dto.tsファイルが生成される.responseはsignUpへの応答であり、readonly readOnlyData(ButchelField)はreadonreadOnlyDataであるため、cat.dto.tsもそれに対応するコードのみを記述する.
ファイル内のコードは以下の通りです.

export class ReadOnlyCatDto {
  @ApiProperty({
    example: '3425343334',
    description: 'id',
  })
  id: string;
  
  @ApiProperty({
    example: '[email protected]',
    description: 'email',
  })
  email: string;
  
  @ApiProperty({
    example: '김가나',
    description: 'name',
  })
  name: string;
}

ステータス値の説明は、@ApiResponseデコーダを使用して設定することができる.

  @ApiResponse({
    status: 500,
    description: 'Server Error...',
  })
  @ApiResponse({
    status: 200,
    description: '성공',
    type: ReadOnlyCatDto
  })
  @ApiOperation({ summary: '회원가입' })

500エラーが発生した場合と200成功した場合にそれぞれ記入します.typeは、これまで使用したrequestDtoではなく、応答のためのDTOであるべきである.

Swaggerを使用(3)-安全設定

Swagerドキュメントが露出すると、深刻なセキュリティ上の問題が発生する可能性があります.だからスワーガーを警備するexpress-basic-authライブラリを使用してセキュリティ設定を行います.

npm install express-basic-auth

// main.ts

import * as expressBasicAuth from 'express-basic-auth';

インストールとimportが完了したら、main.tsにミドルウェアを追加します.

  app.use(
    ['/docs', '/docs-json'],
    expressBasicAuth({
      challenge: true,
      users: { [process.env.SWAGGER_USER]: process.env.SWAGGER_PASSWORD },
    }),
  );

SWAGGER_USERは/docsへの接続を試みる際に必要なIDであり、SWAGGER_PASSWORDはパスワードであり、.envに環境変数として格納される.ここに設定すると、次のスクリーンショットのようにログインする必要があります.