Spring Boot 스웨거(Swagger UI) 적용

Swagger UI

• 프론트엔드와 백엔드간의 협업에 사용되는 툴이다.
• API를 시각화하는 코드가 자동으로 생성되게 해준다.
• RestDocs와 달리 스웨거 웹페이지에서 API를 실행해볼 수 있다.
• API 명세서를 직접 작성할 필요가 없어져 API 명세서 유지보수가 쉬워진다.

스웨거 웹페이지 주소

1. 2.x.x 버전 : localhost:8080/swagger-ui.html
2. 3.x.x 버전 : localhost:8080/swagger-ui/index.html

의존성 : implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0'

 

config 설정

@Configuration
public class SwaggerConfig {

    // 모든 열거형이 별도의 스키마로 추출되어 components 섹션에 정의된다.
    static {
        io.swagger.v3.core.jackson.ModelResolver.enumsAsRef = true;
    }
	
    // api 버전별로 api를 나눌 수 있게 해주는 설정
    @Bean
    public GroupedOpenApi v1OpenAPI() {
        return GroupedOpenApi.builder()
                .group("v1") // 그룹의 이름을 설정
                .pathsToMatch("/api/v1/**") // 이 그룹에 들어갈 api를 설정
                .addOpenApiCustomizer(openApi -> openApi.info(v1Info())) // OpenApi 설정 추가
                .build();
    }

    private Info v1Info() {
        return new Info()
                .title("Study With Me API") // 제목 설정
                .version("1.0") // 버전 설정
                .description("API version 1 documentation"); // 설명 설정
    }
    
    /* 그룹별로 안 나눌 시에 OpenApi 설정
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(apiInfo());
    }
    */
}

 

yml 설정

springdoc:
  swagger-ui:
    operations-sorter: method // HTTP 메소드에 따라 정렬

 

OpenApi가 아닌 GroupedOpenApi를 설정하면 사진 상단에 'Select a definition' 부분이 생긴다. 여기서 그룹을 선택할 수 있다.

 

@Tag

• 컨트롤러에 존재한 API를 그룹화할 태그명을 지정할 수 있다.
• 만약 태그명을 지정하지 않는다면, AuthController의 경우 auth-controller로 변환하여 API를 그룹화 한다.
• 만약 서로 다른 컨트롤러에 대해 같은 name을 적용하면 하나로 합쳐진다.

위에는 @Tag 적용, 아래는 적용 X

@RestController
@RequiredArgsConstructor
@RequestMapping("/api")
@Tag(name = "Study", description = "<b>[스터디]</b> API")
public class StudyCommandController {

 

@Operation : 각 API에 대한 설명을 추가할 수 있다.

@Operation(
        summary = "스터디 생성",
        description = "로그인한 유저가 스터디를 생성합니다."
)
public ApiResponse<Void> studyAdd(Principal principal, @Valid @RequestBody CreateStudyRequest request) {

 

@ApiResponse

• 서버에서 사용하는 응답 code과 message 값을 보여줄 수 있다.
• 커스텀 응답 코드를 사용하는 경우라면, 필수적으로 설정해주는 것이 좋다.
• 만약 @ApiResponse에 대해 설정할 것이 많다면 @ApiResponses를 먼저 추가한 다음 @ApiResponse를 넣어주면 된다.

@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "201", description = "성공")
public ApiResponse<Void> studyAdd(Principal principal, @Valid @RequestBody CreateStudyRequest request) {

 

@Schema 

• 스웨거 웹 페이지의 맨 밑에 존재하는 스키마에 대한 정보를 서술할 수 있게 해준다.
• 주로 사용하는 속성값으로는 description, defaultValue, allowableValues가 있다.

@Schema(defaultValue = "NEWEST", allowableValues = {"NEWEST, LIKE, COMMENT"})
private SortCriteria sortCriteria = SortCriteria.NEWEST;