[Nest]Swagger APIの適用

緒論

2つのプロジェクトでGitbookを使用してAPIリストを管理します.最初からGitbookを書いて別のことを書こうとは思っていませんでしたが、プロジェクトをしている間に不便な点を感じたので、代替材料があるか探してみました.その後、Swager APIは自動化とテストをサポートして試用することにした.
私がGitbookしか使っていないときの欠点は、

Gibookの欠点

1.APIの詳細が変更されるたびに、Webページ上で1つずつ変更されます。

これは大きな欠点だと思います.GitbookはほとんどAPIの詳細を管理する手帳なので、設計段階の終了や作成時には非常に簡単ですが、プロジェクト中期にAPIを変更するのは面倒なことではありません.
もちろん,変更が起こらないように設計することが重要であるが,それでもAPIは様々な理由で随時変更される可能性がある.

2.無料バージョンは、作成者のみが変更できます。**

私たちはプロジェクトマネージャが作成したので、後で変更が発生するたびに.
各API担当者がタスクの中で整理した後、組長が再修正した...事が繰り返された.
企業で使うと有料バージョンを使う確率が高いのがTOYアイテムのような小さなアイテムの欠点かもしれません.

Swager APIの利点

では、スワーガーの長所は何でしょうか.Gitbookの欠点は正反対に補うことができる.

1.(半)自動化が可能。

完全に自動化されているのではなく、どのようなコード、タイプなのか、一つ一つ詳細を追加する必要があります.これは同じです.しかし,コードを記述する際には,自然に部分を追加することができ,Webページへの移動と比較できない程度に便利である.

2.APIテストが可能です。

以前はPostmanでAPIテストが必要でした.しかし,作成さえすれば,Swagger APIは文書中で容易にテストできる.
これらの利点を持つSwagger APIをNestJSに適用する方法について説明します.

SwaggerをNestJSに適用する

1.モジュールクローズ

まずnestで使用するためにはnpmでモジュールをダウンロードする必要がある.

// 일반적인 경우
npm install --save @nestjs/swagger swagger-ui express

//fastify를 사용하는 경우
npm install --save @nestjs/swagger fastify-swagger

2.優先パラメータ

そしてメインtsでは、以下のようにプリファレンスパラメータを設定します.

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    cors: true,
  });
  
// 여기부터 Swagger 설정 시작
  const config = new DocumentBuilder()
  .setTitle('Roadgram')
  .setDescription('Roadgram API Document')
  .setVersion('1.0')
  .addTag('roadgram')
  .build();

  const document = SwaggerModule.createDocument(app, config);
  // 첫 번째 변수는 url/변수의 형태로 URL 경로를 설정할 수 있다.
  // ex) localhost:5000/api
  SwaggerModule.setup('api', app, document, {
    // swagger option 중 하나로, 기본적으로 보이는 Dto를 숨기는 option
    swaggerOptions: {defaultModelsExpandDepth: -1}
  });
  
  // Swagger 설정 끝

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    }),
  );

  app.use(cookieParser());
  await app.listen(process.env.SERVER_PORT);
}
bootstrap();

サーバを設定して開き、URL(私が示すようにlocalhost:5000/api)に接続すると、以下のようにドキュメントが表示されます.

3.記録API

レコーダーで記録してみましょう.
アクセサリーに関する情報は正式な書類で確認できます.

-タグの設定

ラベルはApiTagsで分類できます.
各メソッドは、コントローラ全体を同じラベルに組み合わせる場合は、一番上に宣言できます.

@Controller('articles')
@ApiTags('Articles')
export class ArticlesController {
  constructor(
    private articlesService: ArticlesService,
  ) {}

 ....

-APIの説明を追加

説明はsummary、descriptionオプションでApiOperationに追加できます.

  @Get()
  @ApiOperation({summary: "메인 페이지 팔로우 조회", description: "메인 페이지에서 팔로우한 사람의 게시물들을 조회한다."})
 ...

-入力値詳細の追加

DTOを使用する場合は、DTOの各変数にapiプロパティを指定します.
詳細を入力できます.

export class CreateArticleDto {
  @ApiProperty({description: '유저ID'})
  @IsNotEmpty()
  @IsNumber()
  user: number;

それ以外は使用していませんが、ApiQuery、ApiParamなどを使ってController部分に追加することもできます.

-レスポンスの追加

各レスポンスコードには、apikResponse、apiNotFoundResponseなどから対応するコメントを追加できます.

@Get()
  @ApiOperation({summary: "메인 페이지 팔로우 조회", description: "메인 페이지에서 팔로우한 사람의 게시물들을 조회한다."})
  @ApiOkResponse({description: '팔로우 게시물을 정상적으로 조회함', type: GetMainResponse})
  @ApiUnauthorizedResponse({description: '권한이 없음', type: GetMain401Response})
  @ApiNotFoundResponse({description: '팔로잉 유저를 찾을 수 없음', type: GetMain404Response})

typeに対応する応答は独立した抽象クラスとして作成される.

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

export abstract class ArticleObject {
  @ApiProperty({example: 5})
  id: number
  
  @ApiProperty({example: 3})
  userId: number

  @ApiProperty({example: 'thumbnail.jpg'})
  thumbnail: string

  @ApiProperty({example: "테스트 계정"})
  nickname: string

  @ApiProperty({example: "profile.jpg"})
  profileImage: string
  
  @ApiProperty({example: 3})
  totalLike: number

  @ApiProperty({example: 5})
  totalComment: number
  
  @ApiProperty({example: {order: 1, tagName: "테스트"}})
  tags: Object[] | []
};

export abstract class ArticlesData {
  @ApiProperty()
  articles: ArticleObject
};

export abstract class GetMainResponse {
  @ApiProperty()
  data: ArticlesData
  
  @ApiProperty({example: "ok"})
  message: string
}

export abstract class GetMain401Response {
  @ApiProperty({example: 'permisson denied'})
  message: string
}

export abstract class GetMain404Response {
  @ApiProperty({example: 'not found following ids'})
  message: string
}

完成物!

私はすでにコード作成されたプロジェクトにSwaggerを適用しました.
次回は設計段階から実施します.
コードや変数を設定して適用するのは容易ではないようです.途中で交換すべきかもしれません.
それでもGitbookより便利なのは事実
実際の運用でSwagerを使うところはSwagerだけでAPIの内訳を管理するのか、Gitbookなどのツールを併用するのか.
にこにこ

Reference

正式な書類

NestJSでSwaggerを使用する方法

NestjsでSwaggerを使う