엑셀 API 명세서는 그만! 백엔드 개발자의 구원자 'Swagger' 완벽 적용 가이드

안녕하세요, 여러분의 든든한 IT 길잡이 데브프리입니다.

 

백엔드 개발자가 API를 다 만들고 나면, 프론트엔드 개발자가 그 API를 가져다 쓸 수 있도록 설명서인 'API 명세서'를 건네주어야 합니다. 보통 엑셀이나 워드, 노션을 열고 "게시글 조회는 GET 방식이고요, 주소는 /api/board 이고, 파라미터는..." 하면서 한 땀 한 땀 손으로 적기 시작하죠.

 

문제는 백엔드 코드가 바뀔 때마다 이 문서도 일일이 수정해야 한다는 점입니다. 깜빡하고 문서를 수정하지 않으면 프론트엔드 개발자에게 "백엔드님, 명세서랑 데이터가 다르게 오는데요?"라는 원망 섞인 소리를 듣게 됩니다.

 

이런 소통의 지옥에서 우리를 구원해 줄 아주 우아하고 강력한 SW 도구! 코드를 짜면 설명서가 자동으로 만들어지는 마법의 도구 'Swagger(스웨거)'를 소개합니다.

 

1. Swagger, 도대체 어떤 도구인가요? (자동 메뉴판 비유)

Swagger는 내가 작성한 백엔드 코드(컨트롤러)를 쫙 스캔해서, 예쁘고 테스트까지 가능한 웹 페이지 형태의 'API 명세서'로 자동 변환해 주는 강력한 문서화 도구입니다.

Swagger는 주방장이 레시피를 바꾸면 홀에 있는 디지털 메뉴판이 알아서 갱신되는 시스템과 같습니다.

식당에 비유해 볼까요?

과거에는 메뉴가 바뀔 때마다 홀 매니저가 종이 메뉴판(엑셀 명세서)에 화이트를 칠하고 새로 글씨를 적어야 했습니다. 매번 실수도 나오고 시간도 오래 걸렸죠.

 

하지만 Swagger라는 '디지털 자동 메뉴판'을 도입하면, 주방장(개발자)이 주방에서 레시피(코드)만 수정해도 홀에 있는 메뉴판에 실시간으로 새로운 메뉴와 가격이 업데이트됩니다. 심지어 손님(프론트엔드)은 이 메뉴판에서 버튼을 눌러 모의 주문(API 테스트)까지 직접 해볼 수 있습니다!

 

2. Spring Boot 3.x 환경에 Swagger 적용하기 (1분 컷)

적용하는 방법도 너무나 간단합니다. 스프링 부트 프로젝트에 의존성(라이브러리) 하나만 추가해 주면 끝납니다. (과거에는 SpringFox를 많이 썼지만, 최근 스프링 부트 3.x 버전부터는 Springdoc OpenAPI를 표준으로 사용합니다.)

 

build.gradle 파일의 dependencies 블록에 딱 한 줄만 추가하세요.

Groovy

 

dependencies {
    // 💡 이 한 줄이면 스프링 부트가 내 코드를 읽어 API 문서를 자동으로 만들어냅니다!
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
}

추가 후 코끼리 버튼(Gradle Refresh)을 눌러 다운로드를 완료하고, 스프링 부트 서버를 실행합니다. 그리고 브라우저 주소창에 http://localhost:8080/swagger-ui/index.html을 입력해 보세요. 아무것도 한 게 없는데, 내가 만든 컨트롤러들이 예쁜 UI로 정리된 화면이 나타나는 마법을 경험하실 수 있습니다.

 

3. 실무 꿀팁: 프론트엔드가 감동하는 친절한 주석 달기

Swagger가 자동으로 문서를 만들어주긴 하지만, 영어로 된 변수명만 덜렁 있으면 프론트엔드 개발자가 정확한 용도를 파악하기 힘듭니다. 이때 컨트롤러에 Swagger 전용 어노테이션을 살짝 추가해 주면 아주 친절한 설명서가 완성됩니다.

어노테이션을 통해 API의 제목과 설명을 덧붙여주면, 누구나 이해하기 쉬운 완벽한 협업용 문서가 탄생합니다.

Java

 

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@Tag(name = "게시판 API", description = "게시글 작성 및 조회와 관련된 API입니다.")
@RestController
@RequestMapping("/api/board")
public class BoardController {

    @Operation(summary = "게시글 상세 조회", description = "게시글 ID를 입력받아 상세 내용을 조회합니다.")
    @GetMapping("/{id}")
    public BoardDto getBoard(@PathVariable Long id) {
        // 로직 생략
        return new BoardDto();
    }
}

• @Tag: 컨트롤러(클래스) 전체의 큰 주제를 적어줍니다.
• @Operation: 각각의 메서드(API)가 무슨 역할을 하는지 상세히 적어줍니다.

이렇게 적어두면 Swagger 화면에 한글로 된 친절한 설명이 추가되어, 프론트엔드 개발자가 매번 슬랙(Slack)으로 "이 API는 뭐 하는 건가요?"라고 질문하는 횟수가 획기적으로 줄어듭니다.

 

마무리

코딩하기도 바쁜데 문서 작업까지 챙기려다 보면 개발의 흐름이 끊기기 십상입니다.

 

하지만 Swagger를 도입하면 코드가 곧 문서가 되고, 문서가 곧 테스트 도구가 되는 일석이조의 효과를 누릴 수 있습니다. 불필요한 소통 오해를 줄이고, 오로지 핵심 비즈니스 로직에만 집중할 수 있게 도와주는 최고의 생산성 도구입니다.

 

오늘부터 엑셀과 노션은 고이 접어두고, 여러분의 프로젝트에 Swagger를 달아 스마트하게 협업해 보세요!

 

오늘의 IT 실전 가이드가 도움이 되셨다면 공감과 댓글 부탁드립니다. 지금까지 데브프리였습니다. 감사합니다!