안녕하세요. J4J입니다.
이번 포스팅은 spring boot 3 버전 이후 gradle에 swagger 사용 환경 설정하는 방법에 대해 적어보는 시간을 가져보려고 합니다.
들어가기에 앞서
Spring Boot 3 버전이 등장하면서 최근에 생성되는 많은 프로젝트들은 3 버전 환경들이 구성되고 있습니다.
3 버전부터는 3 버전 이전과 설정하는 방법이 달라지기 때문에, 3 버전 이상을 사용하시는 분들만 환경 설정 하는 방법을 참고하시면 될 것 같습니다.
Swagger란?
swagger는 spring에서 사용할 수 있는 API 문서화 도구 중 하나로 개발된 API들에 관련된 정보들을 간편하게 볼 수 있도록 도와줍니다.
일반적으로 swagger를 사용한다고 하면 많이 사용되는 기능이 산출물을 기반으로 한 문서화의 형태를 활용하지만 이 외에도 개발 전 설계를 위한 API 명세를 작성한다거나 API 테스트를 수행하는 기능들도 다양하게 지원을 해줍니다.
swagger를 이용한 문서화를 사용하지 않았을 때와 사용할 때의 가장 큰 차이점은 문서 자동화라고 얘기할 수 있습니다.
spring에 작성된 코드 정보를 기반으로 자동으로 문서를 생성해 주기 때문에 API와 관련된 것들을 수동으로 입력하는 것 없이 간편하게 문서화된 결과물을 확인할 수 있습니다.
프론트 개발자 등과 협업을 하기 위해 개발된 API를 문서화하여 제공해 주는 것은 거의 필수적이기 때문에 spring을 이용하여 API 개발을 하시는 분들은 당연하게 swagger 사용이 자연스럽게 뒤따라옵니다.
Swagger 사용 환경 설정 방법
[ 1. build.gradle 설정 ]
dependencies {
// swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
}
[ 2. swagger config 클래스 추가 ]
package com.jforj.swagger.config;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public GroupedOpenApi boardGroupedOpenApi() {
return GroupedOpenApi
.builder()
.group("board") // group 설정 (API들을 그룹화시켜 그룹에 속한 API들만 확인할 수 있도록 도와줌)
.pathsToMatch("/v1/board/**") // group에 포함될 API endpoint 경로
.addOpenApiCustomizer(
openApi ->
openApi
.setInfo(
new Info()
.title("board api") // API 제목
.description("게시판 업무 처리를 위한 API") // API 설명
.version("1.0.0") // API 버전
)
)
.build();
}
}
[ 3. dto / controller 클래스 추가 ]
// request dto
package com.jforj.swagger.dto;
public record BoardTitlesRequestDto(
String title
) {
}
// response dto
package com.jforj.swagger.dto;
import lombok.Builder;
import java.util.List;
@Builder
public record BoardTitlesResponseDto(
List<String> titles
) {
}
// controller
package com.jforj.swagger.controller;
import com.jforj.swagger.dto.BoardTitlesRequestDto;
import com.jforj.swagger.dto.BoardTitlesResponseDto;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
@RestController
@RequestMapping("/v1/board")
public class BoardController {
@GetMapping("/titles")
public ResponseEntity<BoardTitlesResponseDto> getTitles(BoardTitlesRequestDto boardTitlesRequestDto) {
List<String> titles = Arrays.asList(
"첫 번째 게시글 제목",
"블로그에 대한 공지사항을 알려드립니다.",
"누구나 작성할 수 있는 블로그",
"블로그의 모든 것"
);
return ResponseEntity.ok(
BoardTitlesResponseDto
.builder()
.titles(
titles
.stream()
.filter(title -> title.contains(boardTitlesRequestDto.title()))
.collect(Collectors.toList())
)
.build()
);
}
}
사용 환경 설정 테스트
코드를 위와 같이 작성하면 swagger에 접속할 경우 프로젝트 내부에 생성된 API들 중 /v1/board 경로 하위에 속하는 모든 API들을 확인할 수 있습니다.
swagger 접속 경로는 {서버 도메인}/swagger-ui/index.html이기 때문에 일반적으로 다음과 같이 http://localhost:8080/swagger-ui/index.html을 입력하면 확인 가능합니다.
이곳에서 swagger config 클래스 파일에 설정한 정보들도 모두 확인할 수 있습니다.
- 빨간색 - group
- 주황색 - title
- 보라색 - description
- 파란색 - version
Tag 및 Schema 설정
위에서 설정한 것 만으로 swagger와 사용되는 API는 모두 연결되어 자동으로 문서화를 제공해 줄 수 있습니다.
하지만 현재는 개발된 API가 어떤 API인지, API 처리에 사용되는 dto들은 어떤 객체들인지에 대한 부가 설명이 표현되지 않습니다.
문서를 처음보는 사용자들에게 이런 부가적인 정보들을 제공해 줄 수 있는 것이 tag와 schema를 사용하는 것입니다.
tag와 schema를 사용하게 되면 다음과 같이 swagger 정보가 변경되는 것을 확인할 수 있습니다.
// request dto
package com.jforj.swagger.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.Builder;
import java.util.List;
// tag 추가
@Tag(name = "board title response dto 객체", description = "board title API를 요청 처리가 완료되었을 때 응답되는 객체")
@Builder
public record BoardTitlesResponseDto(
// schema 추가
@Schema(title = "게시판 제목 목록", description = "필터 처리가 수행되며 조회된 게시판 제목 목록")
List<String> titles
) {
}
// response dto
package com.jforj.swagger.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.tags.Tag;
// tag 추가
@Tag(name = "board title request dto 객체", description = "board title API를 요청할 때 함께 전달되어야 하는 객체")
public record BoardTitlesRequestDto(
// schema 추가
@Schema(title = "게시판 제목", description = "게시판 제목을 조회할 때 필터 처리를 위해 사용되는 제목")
String title
) {
}
// controller
package com.jforj.swagger.controller;
import com.jforj.swagger.dto.BoardTitlesRequestDto;
import com.jforj.swagger.dto.BoardTitlesResponseDto;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
// tag 추가
@Tag(name = "board controller api", description = "게시판에 사용되는 API")
@RestController
@RequestMapping("/v1/board")
public class BoardController {
@GetMapping("/titles")
public ResponseEntity<BoardTitlesResponseDto> getTitles(BoardTitlesRequestDto boardTitlesRequestDto) {
List<String> titles = Arrays.asList(
"첫 번째 게시글 제목",
"블로그에 대한 공지사항을 알려드립니다.",
"누구나 작성할 수 있는 블로그",
"블로그의 모든 것"
);
return ResponseEntity.ok(
BoardTitlesResponseDto
.builder()
.titles(
titles
.stream()
.filter(title -> title.contains(boardTitlesRequestDto.title()))
.collect(Collectors.toList())
)
.build()
);
}
}
Group 추가
group을 설정하면 group 별 보이고 싶은 API들만 모아서 확인할 수 있도록 도와줍니다.
게시판 처리와 관련된 API들만 모으거나, 사용자 처리와 관련된 API들만 모으는 등의 방식을 활용하여 보다 편하게 문서를 확인할 수 있도록 도와주는 기능입니다.
지금까지 위에서 설정된 것들을 보면 swagger config 클래스 파일 설정한 것을 보면 group 설정을 한 것을 확인할 수 있습니다.
그리고 swagger에 접속을 해보면 group을 선택하여 group에 속하는 API들만 볼 수 있습니다.
현재 설정을 기반으로 group을 새롭게 추가하여 어떻게 swagger에서 보이는지 확인해 보겠습니다.
[ 1. swagger config 클래스 변경 ]
package com.jforj.swagger.config;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfig {
@Bean
public GroupedOpenApi boardGroupedOpenApi() {
return GroupedOpenApi
.builder()
.group("board") // group 설정 (API들을 그룹화시켜 그룹에 속한 API들만 확인할 수 있도록 도와줌)
.pathsToMatch("/v1/board/**") // group에 포함될 API endpoint 경로
.addOpenApiCustomizer(
openApi ->
openApi
.setInfo(
new Info()
.title("board api") // API 제목
.description("게시판 업무 처리를 위한 API") // API 설명
.version("1.0.0") // API 버전
)
)
.build();
}
// user group 추가
@Bean
public GroupedOpenApi userGroupedOpenApi() {
return GroupedOpenApi
.builder()
.group("user")
.pathsToMatch("/v1/user/**") // group에 포함될 API endpoint 경로
.addOpenApiCustomizer(
openApi ->
openApi
.setInfo(
new Info()
.title("user api") // API 제목
.description("사용자 처리를 위한 API") // API 설명
.version("1.0.0") // API 버전
)
)
.build();
}
}
[ 2. controller 클래스 추가 ]
package com.jforj.swagger.controller;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Arrays;
import java.util.List;
@Tag(name = "user controller api", description = "사용자 처리에 사용되는 API")
@RestController
@RequestMapping("/v1/user")
public class UserController {
@GetMapping("/names")
public ResponseEntity<List<String>> getNames() {
List<String> names = Arrays.asList(
"김이름",
"최이름",
"진이름"
);
return ResponseEntity.ok(names);
}
}
[ 3. swagger에서 group 목록 확인 ]
[ 4. group 별 swagger에 보이는 API 확인 ]
이상으로 spring boot 3 버전 이후 gradle에 swagger 사용 환경 설정에 대해 간단하게 알아보는 시간이었습니다.
읽어주셔서 감사합니다.
'Spring > SpringBoot' 카테고리의 다른 글
| [SpringBoot] Layer별 테스트 코드 작성하기 (1) - JPA를 이용한 Repository 테스트 (0) | 2024.02.03 |
|---|---|
| [SpringBoot] Spring Validation을 이용한 유효성 검증하기 (1) | 2024.01.29 |
| [SpringBoot] Spring Boot 3 버전 이후 gradle에 querydsl 사용 환경 설정하기 (0) | 2024.01.22 |
| [SpringBoot] @Transactional 사용 방식 정리 (1) | 2023.09.25 |
| [SpringBoot] LocalDateTime 사용하기 (0) | 2023.09.24 |
댓글