2023.09.26 - Swagger(Nest.js)

01. Swagger

• swagger란
  • RESTful 웹 서비스를 문서화하고 테스트하기 위한 강력한 도구와 프레임워크
  • 백엔드 개발자와 프론트 엔드 개발자 간의 협업을 용이하게 하며 API 엔드포인트, 요청 및 응답 형식, 매개변수, 보안 등에 대한 자세한 문서를 생성하는 데 도움을 준다.
  • API 개발 및 관리가 훨씬 효율적이며, BE와 FE 협업을 간소화 할 수 있다.

02. 주요 기능

1. API 문서 생성: API에 대한 자동화된 문서를 생성할 수 있다. 문서에는 엔드포인트, HTTP 메서드(GET, POST, PUT, DELETE 등), 요청 및 응답 형식, 매개변수, 예제 요청 및 응답 등이 자세하게 나와 있다.
2. API 테스트: Swagger UI를 통해 API를 테스트할 수 있다. 사용자는 문서에서 제공하는 매개 변수를 설정하고 API를 호출하여 실제 동작을 확인할 수 있다.
3. API 보안: Swagger를 사용하여 API에 보안 기능을 추가하고 OAuth 또는 API 키와 같은 인증 및 권한 부여 메커니즘을 구현할 수 있다.
4. 코드 생성: Swagger 문서를 기반으로 클라이언트 및 서버 코드를 자동으로 생성할 수 있다. 다양한 프로그래밍 언어와 프레임워크에 대한 지원이 있다.
5. API 버전 관리: Swagger를 통해 API 버전 관리도 용이하게 할 수 있다.

03. 사용법

• Swagger 모듈 설치

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

• Swagger 미들웨어 추가

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

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

  // Swagger 설정
  const config = new DocumentBuilder()
    .setTitle('Your API')
    .setDescription('API description')
    .setVersion('1.0')
    .addTag('api')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

==> DocumentBuilder를 사용하여 Swagger 문서의 기본 설정을 구성, SwaggerModule.createDocument를 통해 문서를 생성, SwaggerModule.setup으로 Swagger UI를 설정

• 애플리케이션 실행: Swagger 설정을 추가하고 모든 준비가 완료되었으면 애플리케이션을 실행
• Swagger UI 접근: 주소 뒤에 /swagger를 붙이면 문서를 확인 가능하다.

04. 작성 방법

2023.09.30 - Swagger(Nest.js) 작성 방법