Swagger(OpenAPI) 도입 및 API 문서화 적용

Swagger란?

Swagger는 REST API를 자동으로 문서화해주는 도구이다.

Spring Boot 프로젝트에서는 보통 springdoc-openapi 라이브러리를 사용하며,
컨트롤러와 DTO에 작성한 어노테이션을 기반으로 API 문서를 자동 생성한다.

개발자는 별도의 문서를 수작업으로 작성하지 않아도 되고,
Swagger UI를 통해 API 목록, 요청 파라미터, 응답 형식 등을 한눈에 확인할 수 있다.

---

왜 사용하는가?

프로젝트 규모가 커질수록 API 개수가 많아지고, 프론트엔드와 백엔드 간 협업 시 API 명세 공유가 중요해진다.

Swagger를 사용하면:

• API 문서를 자동 생성 가능
• URL, HTTP Method, Request/Response 구조 확인 가능
• 브라우저에서 직접 API 테스트 가능
• 프론트엔드와 협업 시 명세 공유가 쉬움
• 문서와 실제 코드의 불일치 문제 감소

특히 팀 프로젝트에서는 API 명세서를 별도로 관리하지 않아도 최신 상태를 유지할 수 있다는 장점이 있다.

---

Swagger와 OpenAPI의 관계

엄밀히 말하면:

• OpenAPI = API 명세 표준
• Swagger = OpenAPI를 시각화하는 도구

현재 Spring Boot에서는 OpenAPI 스펙을 생성하고, Swagger UI를 통해 화면으로 보여주는 구조를 사용한다. 

---

Spring Boot에서 사용 방법

1. 의존성 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.x.x'

---

2. 컨트롤러 문서화

클래스에는 @Tag를 사용한다.

@Tag(
    name = "채팅방",
    description = "채팅방 생성, 조회, 수정 관련 API"
)
@RestController
@RequestMapping("/api/v1/chat-rooms")
public class ChatRoomController {
}

---

메서드에는 @Operation(오퍼레이션)을 사용한다.

@Operation(summary = "채팅방 생성")
@PostMapping
public ApiResponse<CreateChatRoomResponse> createRoom() {
}

Swagger UI에는 다음과 같이 표시된다.

채팅방
 └─ 채팅방 생성
 └─ 채팅방 조회
 └─ 채팅방 종료

---

3. DTO 문서화

@Schema(description = "채팅방 생성 요청")
public record CreateChatRoomRequest(

    @Schema(description = "채팅방 제목")
    String title,

    @Schema(description = "최대 인원")
    Integer maxMembers
) {
}

Swagger UI에서 각 필드 설명을 확인할 수 있다.

---

우리 프로젝트 적용 방식

SwaggerConfig를 추가한 뒤 각 도메인 Controller에:

• @Tag
• @Operation

을 적용한다.

예시:

• ChatRoomController
• JoinRequestController
• NotificationController
• TranslationController

---

WebSocket(STOMP)는 Swagger 대상이 아니다

Swagger는 HTTP 기반 REST API 문서화 도구이다.

따라서 다음과 같은 API는 문서화 가능하다.

@GetMapping
@PostMapping
@PutMapping
@DeleteMapping

반면 STOMP 기반 WebSocket 컨트롤러는 Swagger가 인식하지 못한다.

@MessageMapping("/chat/rooms/{chatRoomId}/messages")

따라서 ChatMessageController와 같은 STOMP 전용 컨트롤러는 Swagger 문서화 대상에서 제외하는 것이 일반적이다.

---

이번 작업에서 배운 점

처음에는 모든 Controller에 Swagger 어노테이션을 추가해야 하는 줄 알았지만, Swagger는 REST API를 위한 문서화 도구이므로 STOMP WebSocket Controller에는 적용할 의미가 없다는 것을 알게 되었다.

 

따라서 REST Controller에는 @Tag, @Operation을 적용하고, WebSocket 전용 Controller는 제외하는 방향으로 진행하였다.