Swagger로 백엔드 API 문서 자동화하기

nini·2025년 6월 23일

6기기자단 KB KB it's your life Swagger TIL 백엔드

KB IT's Your Life

목록 보기

33/40

ver.Springfox(Swagger2.x)

API 개발을 하다 보면 문서화는 필수이지만, 종종 뒤로 미뤄지곤 합니다.
Swagger는 그런 고민을 해결해주는 도구입니다. 코드 기반으로 문서를 자동 생성하고, UI로 API 테스트까지 할 수 있어 협업과 유지보수가 매우 수월해집니다.

이 글에서는 Swagger를 활용해 프로젝트의 API 문서를 자동화하는 방법을 정리해보겠습니다.

Swagger란?

Swagger는 REST API를 문서화하고 테스트할 수 있게 해주는 오픈소스 도구입니다.
요즘은 OpenAPI Specification(OAS) 라는 이름으로 표준화되어 다양한 도구들이 이를 따르고 있습니다.

=> Swagger는 프론트엔드, 백엔드, QA 모두가 사용하는 실시간 문서 & 테스트 플랫폼이라고 보면 됩니다.

✅ Swagger를 왜 써야 할까?

역할	Swagger가 주는 이점
프론트엔드	API 명세 확인 및 직접 테스트 가능
QA/테스터	별도 도구 없이 UI에서 검증 가능
백엔드 개발자	API 변경 시 자동으로 문서 갱신
협업팀	항상 최신 API 문서 공유 가능

저는 실제로 프로젝트에서 iOS 앱을 개발하며 Swagger를 활용한 경험이 있습니다. 백엔드 팀이 제공한 Swagger 문서를 통해 API 명세를 직관적으로 확인하고, 직접 테스트하면서 응답 결과를 바로 볼 수 있어 개발과 디버깅에 큰 도움이 되었습니다. 협업 효율도 눈에 띄게 높아졌습니다.😃

🥔 프로젝트에 Swagger 적용하기

1. 의존성 추가 (Springfox 기준)

build.gradle

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

2. Swagger 설정 클래스

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private final String API_NAME = "Board API";
    private final String API_VERSION = "1.0";
    private final String API_DESCRIPTION = "Board API 명세서";

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(API_NAME)
                .description(API_DESCRIPTION)
                .version(API_VERSION)
                .build();
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
    }
}

@RestController가 붙은 클래스만 Swagger 문서화 대상으로 설정합니다.
이는 .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) 설정을 통해, API 명세에 REST API 컨트롤러만 포함되도록 필터링한 것입니다.

3. Swagger UI 경로 설정

// WebConfig.java
@Override
protected String[] getServletMappings() {
    return new String[]{
        "/", "/swagger-ui.html",
        "/swagger-resources/**", "/v2/api-docs", "/webjars/**"
    };
}

// ServletConfig.java
registry.addResourceHandler("/swagger-ui.html")
        .addResourceLocations("classpath:/META-INF/resources/");

Swagger UI가 사용하는 HTML, JS 등의 정적 리소스가 정상적으로 로드되도록 경로를 매핑해줍니다.
서블릿 경로와 리소스 위치를 명시적으로 설정해 Swagger 화면이 잘 뜨도록 합니다.

4. 접속 URL 확인

http://localhost:8080/swagger-ui.html

서버가 실행 중일 때 위 주소로 접속하면 Swagger UI를 통해 API 명세를 확인할 수 있습니다.

📝 문서화 어노테이션 활용

Controller에 기본 정보 추가

@Api(tags = "게시글 관리")
@RestController
@RequestMapping("/api/board")
public class BoardController { ... }

API 메서드 설명

@ApiOperation(value = "게시글 목록", notes = "게시글 목록을 얻는 API")
@GetMapping("")
public ResponseEntity<List<BoardDTO>> getList() { ... }

파라미터 설명

@ApiParam(value = "게시글 ID", required = true, example = "1")
@PathVariable Long no

응답 정보 명시

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "성공적으로 요청이 처리되었습니다.", response = BoardDTO.class),
    @ApiResponse(code = 400, message = "잘못된 요청입니다"),
    @ApiResponse(code = 500, message = "서버에서 오류가 발생했습니다.")
})

DTO도 문서화할 수 있다!

@ApiModel(description = "게시글 DTO")
public class BoardDTO {

    @ApiModelProperty(value = "게시글 ID", example = "1")
    private Long no;

    @ApiModelProperty(value = "제목")
    private String title;

    @ApiModelProperty(value = "작성자")
    private String writer;

    // 생략 ...
}

숫자 필드의 example 값은 꼭 숫자로 지정해야 오류를 방지할 수 있어요.

💫 Swagger 사용 시 유의할 점

운영 서버에서는 Swagger UI 보안 설정 필수
- 인증 없이 외부에 Swagger 문서가 노출되면 보안상 매우 위험합니다.
- 운영 환경에서는 Swagger 문서를 비활성화하거나, 인증을 거쳐야만 접근 가능하도록 설정하세요.
개발/운영 환경 분리
- Spring에서는 @Profile("dev") 등으로 환경을 나누고, 개발 환경에서만 Swagger가 동작하도록 설정 가능합니다.
- 이를 통해 운영 서버에서 Swagger가 자동으로 비활성화되게 만들 수 있습니다.
공통 설정 재사용
- 기본 응답 포맷, 공통 헤더 등은 Swagger 설정 전용 Configuration 클래스를 분리해 관리하세요.
- 유지보수와 재사용성이 높아집니다.