Nx NestJs - OpenApi/Swagger 사양을 자동 생성하는 방법

안녕하세요 여러분, 이번에는 짧은 기사입니다.
Nx와 함께 NestJ를 사용하기 시작하면서 우발적인 상황을 발견했습니다. 자동 문서화 옵션을 사용하여 NestJ에서 OpenApi/Swagger를 활성화하는 방법에 대한 논쟁이 여전히 있습니다.

더 이상 두려워하지 마세요. 이 튜토리얼이 끝나면 문제가 해결될 것입니다.

사용된 버전

NestJs 8.0 및 NestJs Swagger 5.2와 함께 작성 당시 V14인 최신 Nx를 사용하고 있습니다.

패키지

빠른 설치npm install --save @nestjs/swagger swagger-ui-express를 사용하는 경우 빠른 설치npm install --save @nestjs/swagger fastify-swagger를 사용하려면 필요한 패키지를 먼저 설치하십시오.

Swagger 모듈 추가

NestJ의 프로젝트 폴더에서 main.ts에 다음을 추가합니다.

function setupOpenApi(app: INestApplication) {
  const config = new DocumentBuilder().setTitle('API Documentation').setVersion('1.0').addTag('api').build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);
}

그런 다음 bootstrap 함수에서 setupOpenApi 함수를 호출합니다.

내 전체main.ts는 다음과 같습니다. 다음 옵션을 선호합니다.

Express 미들웨어에 크게 의존하지 않고 성능을 향상시키기 때문에 Fastify를 사용했습니다

.

전역 접두사를 사용했기 때문에 위의 함수에서 useGlobalPrefix:true를 설정해야 했습니다

.

내가 사용한 전역 접두사는 문서에서 우연히 api인 OpenApi의 기본 경로와 충돌하는 기본값api입니다. useGlobalPrefix: true 플래그를 추가하지 않고 이와 같이 유지하면 http://localhost:3000/api에서 API와 OpenAPI 모두에 액세스할 수 있지만 사용된 globalPrefix가 포함되어 있지 않으므로 문서가 잘못되었음을 알 수 있습니다. .
이 문제를 해결하려면 OpenAPI에 대한 useGlobalPrefix: true 플래그를 설정하고 http://localhost:3000/api/api에서 문서에 액세스해야 합니다. 이상하게 보이므로 http://localhost:3000/api/openApi로 사용자 정의했습니다.
작업 예 벨로우즈:

/**
 * This is not a production server yet!
 * This is only a minimal backend to get started.
 */
import { INestApplication, Logger } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

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

async function bootstrap() {
  const fastifyOptions: ConstructorParameters<typeof FastifyAdapter>[0] = {
    logger: true,
  };
  const fastifyAdapter = new FastifyAdapter(fastifyOptions);
  const app = await NestFactory.create<NestFastifyApplication>(AppModule, fastifyAdapter);

  const globalPrefix = 'api';
  app.setGlobalPrefix(globalPrefix);
  setupOpenApi(app);

  const port = process.env.PORT || 3333;
  await app.listen(port);
  Logger.log(`🚀 Application is running on: http://localhost:${port}/${globalPrefix}`);
}

bootstrap();

function setupOpenApi(app: INestApplication) {
  const config = new DocumentBuilder().setTitle('API Documentation').setVersion('1.0').addTag('api').build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('openApi', app, document, { useGlobalPrefix: true });
}

지금 패키지의 수동 설명서 부분을 사용할 준비가 되었습니다.

자동 문서화

이것은 다소 짧을 것입니다. 우리는 이것을 할 수 있는 2가지 비해키 방법을 가질 것입니다.

Nest-Cli.json - 제안하지 않음

프로젝트의 루트에 nest-cli.json 파일을 만든 다음 추가하십시오.

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "apps",
  "compilerOptions": {
    "plugins": [
      {
        "name": "@nestjs/swagger/plugin",
        "options": {
          "dtoFileNameSuffix": [".entity.ts", ".dto.ts"],
          "controllerFileNameSuffix": [".controller.ts"],
          "classValidatorShim": true,
          "dtoKeyOfComment": "description",
          "controllerKeyOfComment": "description",
          "introspectComments": true
        }
      }
    ]
  }
}

위의 설정을 두려워하지 마십시오. 보다 명확하게 하기 위한 기본값일 뿐입니다. 실제로 변경된 것은 sourceRoot NX의 경우(최소한 앱이 있는 사전 설정의 경우) 폴더apps입니다.

이렇게 하면 매개변수와 클래스 이름을 감지할 수 있지만 클래스 내부에 무엇이 있는지 볼 수 없고 비어 있는 것으로 표시될 가능성이 큽니다.

TsPlugin - 권장, 더 많은 사용자 지정 가능

NestJ의 프로젝트 폴더에 있는 project.json 또는 이전 버전의 경우 루트 폴더에 있는 angular.json로 이동하여 필요한 프로젝트를 검색합니다. build 명령을 변경해야 합니다.

전체 빌드 명령이 다음과 같이 표시됩니다.

 "build": {
      "executor": "@nrwl/node:webpack",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/api",
        "main": "apps/api/src/main.ts",
        "tsConfig": "apps/api/tsconfig.app.json",
        "tsPlugins": [
          {
            "name": "@nestjs/swagger/plugin",
            "options": {
              "dtoFileNameSuffix": [".entity.ts", ".dto.ts"],
              "controllerFileNameSuffix": [".controller.ts"],
              "classValidatorShim": true,
              "dtoKeyOfComment": "description",
              "controllerKeyOfComment": "description",
              "introspectComments": true
            }
          }
        ],
        "assets": ["apps/api/src/assets"]
      },

알 수 있듯이 위의 문서에 지정된 대로 사용자 정의 Webpack TsPlugin을 추가했습니다https://docs.nestjs.com/openapi/cli-plugin#integration-with-ts-jest-e2e-tests.

언급했듯이 이것은 권장되는 접근 방식이며 프로젝트로 가져오는 한 모노 리포지토리의 모든 클래스를 볼 수 있습니다.

최종 세부 정보

다음 사항에 유의하십시오.

class es interface es

만 사용할 수 있습니다.

를 변경하지 않는 한 .dto.ts 또는 .entity.ts를 추가해야 합니다.

읽어 주셔서 감사합니다!