[SpringBoot] REST API 자동 문서화 : Swagger & SpringDoc

API를 개발할 때, 문서를 따로 작성하는 대신 자동으로 문서화하는 것이 효율적이다.
이때 SpringBoot에서 많이 쓰이는 도구 중에 하나인 Swagger와 SpringDoc에 대해 알아보자!

🌐 Swagger

• REST API를 문서화하고 브라우저에서 직접 테스트할 수 있는 도구
• Swagger UI를 통해 API 엔드포인트를 실행하고 응답을 직접 확인 가능
• 백엔드 ↔ 프론트엔드 협업, 외부 연동 팀에서도 API 구조를 직관적으로 확인할 수 있음

---

🌐 SpringDoc

• SpringBoot에서 Swagger를 쉽게 사용할 수 있도록 도와주는 라이브러리
• @RestController, @RequestMapping, @Operation 같은 스프링 애노테이션을 기반으로 자동으로 OpenAPI 문서 생성
• 예전에는 springfox를 썼지만, 현재는 springdoc-openapi가 표준처럼 쓰임

---

🌐 Swagger 적용 방법

1. 의존성 추가

Maven Repository 에서 최신 버전 확인 후 build.gradle.kts에 추가

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

---

2. SpringDoc 도입

@Configuration
@OpenAPIDefinition
public class SpringDoc {
}

• SpringDoc은 프로젝트 전반의 컨트롤러와 엔드포인트를 스캔하여 문서를 생성하기 때문에, 프로젝트의 최상단 패키지에 두는 것이 일반적이다.
• @OpenAPIDefinition : Springdoc에서 API 문서의 전역 메타데이터를 정의할 때 사용하는 어노테이션

---

3. 실행 후 접속

스프링부트를 실행하면 자동으로 Swagger UI를 확인할 수 있다.

• Swagger UI : http://localhost:8080/swagger-ui/index.html

정상적으로 설정했다면 아래와 같은 Swagger 화면이 보일 것이다.

---

4. Swagger에서 API 테스트하기

• Swagger UI는 단순히 API 문서를 보여주는 것에서 끝나지 않고, 문서 내에서 직접 API를 호출하고 응답을 확인할 수 있는 테스트 도구 역할도 한다.
• 하단의 이미지는 Swagger를 직접 GET 요청을 하고 응답을 확인한 모습이다.

Swagger를 처음 실행하면 기본적인 정보만 표시되어 가독성이 떨어진다. 따라서 프로젝트에 맞게 문서를 구조화하고 이해하기 쉽게 만들기 위해서는 별도의 커스터마이징 과정이 필요하다.
이를 위해 Swagger의 다양한 어노테이션을 통해 간단한 커스터마이징도 직접 진행해보도록 하자!

---

🌐 Swagger 문서 커스터마이징

해당 화면처럼 단계별로 커스터마이징을 해보자.

1. SpringDoc 수정

• 전역 문서 정보 설정
  @OpenAPIDefinition을 사용해 API 문서의 제목, 설명, 버전을 지정

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

• GroupedOpenApi를 통한 API 그룹 분리
  하나의 프로젝트 안에 여러 API가 있을 경우, Swagger UI에서 그룹별로 분리해서 관리할 수 있다.

    @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();
    }

• SpringDoc 최종 코드 & Swagger 화면
  

	@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();
    }

}

---

2. Controller 클래스 단위에 @Tag 설정

• @Tag : 여러 API 엔드포인트(클래스 단위)를 Swagger 문서에서 하나의 그룹으로 묶어 표현하는 어노테이션
• controller 클래스 단위에 적용하면 Swagger UI에 "글 API", "댓글 API"라는 그룹이 생기고 그 안에 해당 controller 클래스의 엔드포인트들이 들어가는 것을 볼 수 있다.

---

3. 메소드 단위에 @Operation 설정

• @Operation : 하나의 API 엔드포인트(메소드 단위)를 Swagger 문서에 어떻게 표현할지 정의하는 어노테이션
• summary : API에 대한 간단 설명
• description : API에 대한 상세 설명
• 메소드 단위에 적용하면 Swagger UI에 각 엔드포인트에 대한 설명이 추가되어 표시된다.
  

---

4. Swagger UI 기본 응답 포맷 변경

Swagger UI를 처음 실행하면 각 요청의 Responses -> Media type이 json이 아닌 다른 형식으로 표시되어있다.
모든 API 문서의 기본 응답 타입을 json으로 고정하기 위해 application.yml 에 아래 설정을 추가하고 재실행해보자

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

Responses의 Media type이 applcation/json으로 바뀐 것을 확인할 수 있다.

---