Merge pull request #154 from boostcampwm-2024/Feature/#149_swagger_세팅

Feature/#149 Swagger API 문서 구축

server/package.json

@@ -31,6 +31,7 @@
     "@nestjs/passport": "^10.0.3",
     "@nestjs/platform-express": "^10.0.0",
     "@nestjs/platform-socket.io": "^10.4.7",
+    "@nestjs/swagger": "^8.0.7",
     "@nestjs/websockets": "^10.4.7",
     "@noctaCrdt": "workspace:*",
     "bcrypt": "^5.1.1",

server/src/app.controller.ts

@@ -1,12 +1,15 @@
-// server/src/app.controller.ts
-import { Controller, Get, Injectable } from "@nestjs/common";
+import { Controller, Get } from "@nestjs/common";
+import { ApiTags, ApiOperation, ApiResponse } from "@nestjs/swagger";
 import { AppService } from "./app.service";
 
+@ApiTags("app")
 @Controller()
 export class AppController {
   constructor(private readonly appService: AppService) {}
 
   @Get()
+  @ApiOperation({ summary: "Get a greeting message" })
+  @ApiResponse({ status: 200, description: "Successfully retrieved greeting message." })
   public getHello(): string {
     return this.appService.getHello();
   }

server/src/auth/auth.controller.ts

@@ -1,13 +1,35 @@
 import { Controller, Post, Body, Request, UseGuards } from "@nestjs/common";
 import { AuthService } from "./auth.service";
 import { JwtAuthGuard } from "./jwt-auth.guard";
+import { ApiTags, ApiOperation, ApiBody, ApiResponse } from "@nestjs/swagger";
+import { UserDto } from "./dto/user.dto";
 
+@ApiTags("auth")
 @Controller("auth")
 export class AuthController {
   constructor(private authService: AuthService) {}
 
   @Post("register")
-  async register(@Body() body: { email: string; password: string; name: string }) {
+  @ApiOperation({ summary: "Register a new user" })
+  @ApiBody({
+    schema: {
+      type: "object",
+      properties: {
+        email: { type: "string" },
+        password: { type: "string" },
+        name: { type: "string" },
+      },
+    },
+  })
+  @ApiResponse({
+    status: 201,
+    description: "The user has been successfully created.",
+    type: UserDto,
+  })
+  @ApiResponse({ status: 400, description: "Bad Request" })
+  async register(
+    @Body() body: { email: string; password: string; name: string },
+  ): Promise<UserDto> {
     const { email, password, name } = body;
     const user = await this.authService.register(email, password, name);
     return {
@@ -18,6 +40,18 @@ export class AuthController {
   }
 
   @Post("login")
+  @ApiOperation({ summary: "Login a user" })
+  @ApiBody({
+    schema: {
+      type: "object",
+      properties: {
+        email: { type: "string" },
+        password: { type: "string" },
+      },
+    },
+  })
+  @ApiResponse({ status: 200, description: "The user has been successfully logged in." })
+  @ApiResponse({ status: 401, description: "Unauthorized" })
   async login(@Body() body: { email: string; password: string }) {
     const user = await this.authService.validateUser(body.email, body.password);
     if (!user) {
@@ -28,6 +62,9 @@ export class AuthController {
 
   @UseGuards(JwtAuthGuard)
   @Post("profile")
+  @ApiOperation({ summary: "Get user profile" })
+  @ApiResponse({ status: 200, description: "The user profile has been successfully retrieved." })
+  @ApiResponse({ status: 401, description: "Unauthorized" })
   getProfile(@Request() req) {
     return req.user;
   }

server/src/auth/dto/user.dto.ts

@@ -0,0 +1,21 @@
+import { ApiProperty } from "@nestjs/swagger";
+
+export class UserDto {
+  @ApiProperty({
+    description: "The unique identifier of the user",
+    example: "5f8f8c44b54764421b7156c9",
+  })
+  id: string;
+
+  @ApiProperty({
+    description: "The email address of the user",
+    example: "[email protected]",
+  })
+  email: string;
+
+  @ApiProperty({
+    description: "The name of the user",
+    example: "John Doe",
+  })
+  name: string;
+}

server/src/main.ts

@@ -1,5 +1,6 @@
 import { NestFactory } from "@nestjs/core";
 import { AppModule } from "./app.module";
+import { createSwaggerDocument } from "./swagger/swagger.config";
 
 const bootstrap = async () => {
   const app = await NestFactory.create(AppModule);
@@ -27,6 +28,8 @@ const bootstrap = async () => {
 
   app.setGlobalPrefix("api");
 
+  createSwaggerDocument(app);
+
   await app.listen(process.env.PORT ?? 3000);
 };
 bootstrap();

server/src/swagger/swagger.config.ts

@@ -0,0 +1,17 @@
+import { INestApplication } from "@nestjs/common";
+import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";
+
+export const createSwaggerDocument = (app: INestApplication): void => {
+  if (process.env.NODE_ENV !== "development") {
+    return; // 개발 환경이 아니면 Swagger 비활성화
+  }
+
+  const config = new DocumentBuilder()
+    .setTitle("Nocta API Docs")
+    .setDescription("Nocta API description")
+    .setVersion("1.0.0")
+    .build();
+
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup("api-docs", app, document);
+};