icon

Swagger를 이용한 API 문서화

 Swagger(OpenAPI)는 RESTful API를 설계, 빌드, 문서화 및 사용하기 위한 오픈 소스 소프트웨어 프레임워크입니다.

 NestJS와 Swagger를 함께 사용하면 자동화된 API 문서를 쉽게 생성하고 관리할 수 있습니다.

Swagger 개념과 중요성

 Swagger는 API의 구조를 시각적으로 표현하여 개발자와 사용자 간의 커뮤니케이션을 원활하게 합니다.

 API 문서화의 중요성

  1. 명확한 API 스펙 제공
  2. 클라이언트 개발 용이성 향상
  3. API 테스트 및 디버깅 효율성 증대
  4. 프로젝트 유지보수성 개선

NestJS 프로젝트에 Swagger 설정

  1. 패키지 설치
npm install --save @nestjs/swagger swagger-ui-express
  1. main.ts 파일에 Swagger 설정 추가
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
 
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API description')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);
 
  await app.listen(3000);
}
bootstrap();

주요 Swagger 데코레이터 사용

  1. @ApiTags
import { ApiTags } from '@nestjs/swagger';
 
@ApiTags('users')
@Controller('users')
export class UsersController {}
  1. @ApiOperation
import { ApiOperation } from '@nestjs/swagger';
 
@Post()
@ApiOperation({ summary: 'Create user', description: 'Create a new user' })
create(@Body() createUserDto: CreateUserDto) {}
  1. @ApiResponse
import { ApiResponse } from '@nestjs/swagger';
 
@Get(':id')
@ApiResponse({ status: 200, description: 'The found record', type: User })
@ApiResponse({ status: 404, description: 'Record not found' })
findOne(@Param('id') id: string) {}
  1. DTO 문서화
import { ApiProperty } from '@nestjs/swagger';
 
export class CreateUserDto {
  @ApiProperty({ example: 'John Doe', description: 'The name of the user' })
  name: string;
 
  @ApiProperty({ example: 'john@example.com', description: 'The email of the user' })
  email: string;
}

Swagger UI 커스터마이징

 Swagger UI 테마 및 옵션 설정

SwaggerModule.setup('api', app, document, {
  swaggerOptions: {
    tagsSorter: 'alpha',
    operationsSorter: 'alpha',
  },
  customCss: '.swagger-ui .topbar { display: none }',
  customJs: '/custom.js',
});

보안 스키마 추가

 JWT 인증 스키마 추가

const config = new DocumentBuilder()
  .setTitle('My API')
  .setDescription('API description')
  .setVersion('1.0')
  .addBearerAuth()
  .build();
 
// 컨트롤러에서 사용
@ApiBearerAuth()
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@Request() req) {
  return req.user;
}

 OAuth2 스키마 추가

const config = new DocumentBuilder()
  .setTitle('My API')
  .setDescription('API description')
  .setVersion('1.0')
  .addOAuth2()
  .build();
 
// 컨트롤러에서 사용
@ApiOAuth2(['read'])
@Get('items')
findAll() {
  // ...
}

복잡한 데이터 모델 문서화

 중첩 객체 및 배열 표현

export class CreateUserDto {
  @ApiProperty({ example: 'John Doe', description: 'The name of the user' })
  name: string;
 
  @ApiProperty({
    example: { street: '123 Main St', city: 'Anytown' },
    description: 'The address of the user'
  })
  address: {
    street: string;
    city: string;
  };
 
  @ApiProperty({
    type: [String],
    example: ['reading', 'cycling'],
    description: 'User hobbies'
  })
  hobbies: string[];
}

API 버전 관리와 Swagger 연계

 버전별 Swagger 문서 생성

const options = new DocumentBuilder()
  .setTitle('My API')
  .setDescription('API description')
  .setVersion('1.0')
  .addTag('v1')
  .build();
const v1Document = SwaggerModule.createDocument(app, options, {
  include: [UsersModuleV1, PostsModuleV1],
});
SwaggerModule.setup('api/v1', app, v1Document);
 
const v2Options = new DocumentBuilder()
  .setTitle('My API')
  .setDescription('API description')
  .setVersion('2.0')
  .addTag('v2')
  .build();
const v2Document = SwaggerModule.createDocument(app, v2Options, {
  include: [UsersModuleV2, PostsModuleV2],
});
SwaggerModule.setup('api/v2', app, v2Document);

CI/CD 파이프라인에서 Swagger 사용

 Jenkins 파이프라인 예시

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'npm install'
                sh 'npm run build'
            }
        }
        stage('Generate Swagger') {
            steps {
                sh 'npm run swagger:generate'
            }
        }
        stage('Deploy Swagger') {
            steps {
                sh 'aws s3 sync ./swagger-docs s3://my-bucket/api-docs'
            }
        }
    }
}

 Swagger 문서 생성 스크립트 (package.json)

{
  "scripts": {
    "swagger:generate": "node swagger-generate.js"
  }
}

 swagger-generate.js

const { NestFactory } = require('@nestjs/core');
const { SwaggerModule, DocumentBuilder } = require('@nestjs/swagger');
const { AppModule } = require('./dist/app.module');
const fs = require('fs');
 
async function generateSwaggerJson() {
  const app = await NestFactory.create(AppModule);
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API description')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  fs.writeFileSync('./swagger-docs/swagger.json', JSON.stringify(document));
  await app.close();
}
 
generateSwaggerJson();

Swagger 문서와 API 동작의 일관성 유지

  1. API 테스팅 도구 활용 (예 : Postman, Jest)
describe('Users API', () => {
  it('should create a user', async () => {
    const response = await request(app.getHttpServer())
      .post('/users')
      .send({ name: 'John Doe', email: 'john@example.com' })
      .expect(201);
 
    expect(response.body).toHaveProperty('id');
    expect(response.body.name).toBe('John Doe');
  });
});
  1. 자동화된 Swagger 유효성 검사
npm install --save-dev swagger-cli

 package.json에 스크립트 추가

{
  "scripts": {
    "swagger:validate": "swagger-cli validate ./swagger-docs/swagger.json"
  }
}

Best Practices 및 주의사항

  1. 일관된 명명 규칙 사용
  2. 모든 API 엔드포인트 문서화
  3. 예제 값 제공으로 이해도 향상
  4. 보안 정보 노출 주의
  5. 정기적인 문서 업데이트
  6. API 변경 시 문서 동기화 확인
  7. 복잡한 로직은 추가 설명 제공
  8. 에러 응답 상세 문서화
  9. 성능에 미치는 영향 고려 (프로덕션 환경에서 비활성화 고려)
  10. 문서 버전 관리 및 이력 유지

 NestJS에서 Swagger를 이용한 API 문서화는 개발 생산성과 API 품질을 크게 향상시킬 수 있습니다.

 Swagger의 자동 문서 생성 기능과 NestJS의 데코레이터 기반 구조가 잘 조화를 이루어, 최소한의 추가 작업으로 상세하고 정확한 API 문서를 생성할 수 있습니다.

 @nestjs/swagger 모듈이 제공하는 다양한 데코레이터를 활용하면, 컨트롤러와 DTO에 대한 상세한 설명을 쉽게 추가할 수 있습니다.

 이는 단순히 API의 구조를 보여주는 것을 넘어서, 각 엔드포인트의 목적, 예상되는 입출력, 가능한 응답 코드 등 세부적인 정보까지 문서화할 수 있게 해줍니다.

 특히 JWT나 OAuth2와 같은 복잡한 인증 방식을 사용할 때, Swagger 문서는 이를 명확히 설명하는 중요한 도구가 됩니다.

 API 버전 관리와 Swagger 문서화를 연계하면, API의 진화 과정을 명확히 추적하고 관리할 수 있습니다.

 CI/CD 파이프라인에 Swagger 문서 생성 및 배포 과정을 포함시키면, API 변경사항이 자동으로 문서에 반영되어 항상 최신 상태를 유지할 수 있습니다. 이는 문서와 실제 API 동작의 일관성을 보장하는 데 큰 도움이 됩니다.

이전으로다음으로