[Spring] SpringDoc으로 REST API 문서 자동화하기 - Swagger UI 사용법

1. API 문서란?

API 문서는 API를 어떻게 사용해야 하는지 설명하는 문서이다.

프론트엔드 개발자나 다른 백엔드 개발자가 API를 사용할 때 다음과 같은 정보를 확인할 수 있도록 제공한다.

• 어떤 URL로 요청하는지
• 어떤 HTTP Method를 사용하는지
• 어떤 데이터를 전달해야 하는지
• 어떤 응답을 받는지
• 요청 및 응답 데이터의 형식은 무엇인지

2. SpringDoc이란?

SpringDoc은 Spring Boot 프로젝트의 API 정보를 분석해서 OpenAPI 문서를 자동으로 생성해주는 라이브러리이다.

내부적으로 Swagger를 활용하기 때문에 개발자가 API 정보를 일일이 문서로 작성하지 않아도 Swagger UI를 통해 API를 확인할 수 있다.

의존성 추가

build.gradle.kts에 다음 의존성을 추가한다.

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:3.1.0")

3. Swagger UI에서 API 문서 확인하기

SpringDoc을 추가하고 서버를 실행하면 Swagger UI에서 API 문서를 확인할 수 있다.

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

Swagger UI

Swagger UI에서는 등록된 API의

• URL
• HTTP Method
• 요청 파라미터
• 요청 데이터
• 응답 데이터

등을 한눈에 확인할 수 있다.

또한 Swagger UI에서 직접 API를 실행해볼 수도 있어 API 테스트에도 활용할 수 있다.

4. API를 그룹별로 관리하기

API가 많아지면 모든 API가 하나의 목록에 표시되는 것보다 버전이나 용도에 따라 그룹을 나누어 관리하는 것이 편리하다.

SpringDoc에서는 GroupedOpenApi를 이용해 API를 그룹별로 분리할 수 있다.

예를 들어 API V1과 API가 아닌 Home 컨트롤러를 각각 다른 그룹으로 만들 수 있다.

Swagger UI

@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "API 서버",
                version = "beta",
                description = "API 서버 문서입니다."
        )
)
public class SpringDoc {

    @Bean
    public GroupedOpenApi groupApiV1() {
        return GroupedOpenApi.builder()
                .group("apiV1")
                .pathsToMatch("/api/v1/**")
                .build();
    }

    @Bean
    public GroupedOpenApi groupController() {
        return GroupedOpenApi.builder()
                .group("home")
                .pathsToExclude("/api/**")
                .build();
    }
}

주요 설정

group()은 Swagger UI에서 표시할 그룹 이름을 지정한다.

.group("apiV1")

 

pathsToMatch()는 특정 경로에 해당하는 API만 그룹에 포함한다.

.pathsToMatch("/api/v1/**")

 

따라서 /api/v1/로 시작하는 API들이 apiV1 그룹에 포함된다.

반대로 pathsToExclude()는 특정 경로를 그룹에서 제외한다.

.pathsToExclude("/api/**")

 

위 설정에서는 /api/로 시작하는 REST API를 제외하고 나머지 컨트롤러를 home 그룹으로 묶는다.

API 버전별로 그룹을 나누거나 내부용 API와 외부용 API를 구분하는 등의 방식으로 활용할 수 있다.

5. 응답 Media Type 설정하기

Swagger UI

SpringDoc에서는 API 응답의 기본 Media Type도 설정할 수 있다. 

처음에는 설정이 안 되어 있어서 해주는 것이 좋다.

application.yml에 다음과 같이 설정한다.

springdoc:
  default-produces-media-type: application/json

이렇게 설정하면 API 문서에서 기본 응답 형식을 application/json으로 지정할 수 있다.

Swagger UI

다만 HTML을 반환하는 페이지까지 JSON으로 처리하면 안 되므로, HTML을 반환하는 경우에는 별도로 지정할 수 있다.

@GetMapping(produces = MediaType.TEXT_HTML_VALUE)

즉, API는 JSON을 기본으로 사용하고 HTML 응답이 필요한 경우에는 별도로 지정하는 방식이다.

6. 어노테이션으로 API 문서 정보 추가하기

SpringDoc이 API 정보를 자동으로 생성해주지만, 기본 정보만으로는 API의 목적을 정확하게 알기 어려울 수 있다.

이때 어노테이션을 사용해 설명을 추가할 수 있다.

@Tag

Controller 자체에 대한 설명을 추가한다.

@Tag(name = "ApiV1CommentController", description = "댓글 API")
public class PostCommentController {
}

API 그룹에 표시되는 이름과 설명을 지정할 수 있다.

@Operation

특정 API의 설명을 추가한다.

@Operation(summary = "다건 조회")
@GetMapping
public List<PostDto> list() {
    // ...
}

Swagger UI에서 해당 API가 어떤 기능을 수행하는지 쉽게 확인할 수 있다.

Swagger UI