[Spring] Spring Boot + Swagger

• GitHub 저장소: https://github.com/springdoc/springdoc-openapi
• 최신 릴리즈: https://github.com/springdoc/springdoc-openapi/releases
• Maven Central: https://search.maven.org/search?q=g:org.springdoc

 

Swagger

• Swagger는 RESTful API를 설계, 문서화, 테스트할 수 있도록 도와주는 오픈소스 툴 세트이다.
• 현재는 OpenAPI Specification(OAS)이라는 이름으로 공식적으로 관리되며, 그 구현체 중 하나가 Swagger이다.
• Swagger는 API의 명세(Specification)를 기계가 읽을 수 있는 형식(JSON 또는 YAML)으로 작성하고,
  이를 바탕으로 자동 문서화하고, 테스트 인터페이스(UI)까지 제공하는 도구이다.

 

사용법

의존성 추가

25년 3월 기준으로 가장 최신 버전이면서 다운로드가 가장 많은 버전 2.8.6 버전이다.

builde.gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6'

 

이제 

/swagger-ui/index.html 로 접속하면 아래와 같이 자동으로 API 명세 문서가 생성된다.

 

사실 의존성만 추가하면 핵심적인 기능을 사용하는데는 문제가 없다.

 

API 문서 제목, 설명, 버전 명시

@SpringBootApplication 애노테이션 위에 아래의 애노테이션을 추가하면 

@OpenAPIDefinition(
		info = @Info(
				title = "My API",
				version = "v1",
				description = "Swagger 문서 예시입니다."
		)
)

이렇게 표시가 된다.

 

프로필별로 API 문서 제공 활성화/비활성화

application.yml에서 프로필별로 API 문서를 제공할지 말지 정할 수 있다.

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

로컬에선 true로 설정하고, 배포에선 false로 설정할 수 있다.

 

@Tag - 태그 기반 API 그룹화

각 API에 태그를 지정하여, Swagger UI에서 그룹별로 묶어서 보기 쉽게 할 수 있다.

@Tag(name = "User", description = "사용자 관련 API")
@RestController
@RequestMapping("/api/users")
public class UserController {
    ...
}

 

API 설명 커스터마이징

각 API에 대한 설명, 요청/응답 예제 등을 직접 정의할 수 있다.

@Operation

@Operation(summary = "로그인", description = "로그인 이메일과 비밀번호 입력을 하면 로그인 요청을 보냄")
@PostMapping("/sign_in")
public ResponseEntity<Map<String, String>> signIn(@RequestBody LoginMemberDTO loginMemberDto, HttpSession session) {
...

 

 

@Parameter

@GetMapping("/detail/{id}")
    public RecipeDetailDTO getRecipeDetail(
            @Parameter(name = "id", description = "조회할 레시피 ID", example = "1")
            @PathVariable Long id, HttpSession session) {
            ..

Spring Boot에서는 기본적으로 Swagger 문서에 파라미터 정보를 자동으로 표시하긴 하지만, 다음과 같은 한계가 있다

• @PathVariable, @RequestParam의 이름은 알 수 있지만 설명은 없음
• 예시 값(example)이 없어 테스트 시 어떤 값을 넣어야 하는지 불명확함

그래서 @Parameter를 명시적으로 사용하면 Swagger 문서가 더 친절하고 명확해진다.

추가적으로 required 속성을 넣어서 필수인지 아닌지도 표시할 수 있다.

 

@Schema

DTO에 @Schema를 붙이면 Swaager 문서에 상세 설명이 추가된다.

@Getter @Setter
public class LoginMemberDTO
{
    @Schema(description = "사용자 이름", example = "홍길동")
    private String userEmail;

    @Schema(description = "사용자 비밀번호", example = "asd123")
    private String userPw;
}

 

테스트용/운영용 API 서버 명시

테스트용/운영용 API 서버를 명시할 수 있다.

@OpenAPIDefinition(
    servers = {
        @Server(url = "https://dev.example.com", description = "개발 서버"),
        @Server(url = "https://api.example.com", description = "운영 서버")
    }
)
@SpringBootApplication

 

문서 다중 그룹화

API 컨트롤러 구조가 다음과 같다고 가정하자

• /api/user/login
• /api/user/info
• /api/admin/dashboard
• /api/admin/users

 

application.yml에서 아래와 같이 추가할 수 있다.

springdoc:
  group-configs:
    - group: user
      paths-to-match: /api/user/**
    - group: admin
      paths-to-match: /api/admin/**

이 설정대로 Swagger UI를 열면, 상단에 두 개의 그룹이 나뉘어 나타난다

• /v3/api-docs/user → /api/user/** 경로에 해당하는 API만 포함됨
• /v3/api-docs/admin→ /api/admin/** 경로에 해당하는 API만 포함됨

Swagger UI 상단 또는 좌측에서 그룹을 선택할 수 있게 되고, 각 그룹별로 API 문서를 따로 구분해서 확인할 수 있다.