[Spring Boot] 5분만에 Spring Boot 3.x 에 Swagger 적용시키기

1. 개요

API 문서화 툴을 중에서도 특히 Swagger 는 Springdoc 보다도 쉽게 사용할 수 있는 편리한 도구이다. Spring 3.0 버전에서의 API 문서화 툴 사용법을 익히고 적용시켜보자.

2. Swagger 란?

Swagger는 API 문서화 및 테스트에 사용되는 강력한 도구로, RESTful API를 설계, 빌드 및 문서화하는 데 도움을 준다. Swagger를 사용하면 API 엔드포인트, 매개변수, 응답 형식 및 기타 세부 정보를 정의하고 문서로 자동 변환할 수 있다. 이를 통해 API의 이해도를 높이고 개발자 간의 협업을 용이하게 한다.

3. Swagger 사용법

(1) 종속성 추가

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

위 한 줄만 추가하더라도 바로 실행시키면 Swagger 를 적용시킬 수 있다.

하지만 아쉬우니 추가적인 설정 방법에 대해서 더 알아보도록 하자.

(2) Swagger Config

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi userGroupedOpenApi() {
        List<Tag> tags = List.of(new Tag().name("UserController").description("유저 API"));

        return GroupedOpenApi
                .builder()
                .group("user 2.0")
                .pathsToMatch("/api/v2/**")
                .addOpenApiCustomizer(
                        openApi -> {
                            openApi.setTags(tags);
                            openApi.setInfo(
                                    new Info()
                                            .title("user api")
                                            .description("유저 업무 처리를 위한 API")
                                            .version("2.0.0")
                            );
                        }
                )
                .build();
    }

    @Bean
    public GroupedOpenApi groupGroupedOpenApi() {
        List<Tag> tags = List.of(new Tag().name("GroupController").description("그룹 API"));

        return GroupedOpenApi
                .builder()
                .group("group 1.0")
                .pathsToMatch("/api/v1/**")
                .addOpenApiCustomizer(
                        openApi -> {
                            openApi.setTags(tags);
                            openApi.setInfo(
                                    new Info()
                                            .title("group api")
                                            .description("그룹 업무 처리를 위한 API")
                                            .version("1.0.0")
                            );
                        }
                )
                .build();
    }
}

위와 같이 Config 를 추가할 수 있다.

GroupOpenApi 를 사용하면 @Bean 으로 등록하는 수 만큼의 그룹이 생성되고
그룹별로 API 문서를 확인할 수 있다.

한 화면에서 확인할 수 있는 API 문서는 @Bean 에 등록된 GroupedOpenApi 이며, 이는 pathsToMatch("/api/v1/**") 를 기준으로 선별된다.

즉, path 에 따라 화면에 담기는 API 가 달라지게 된다.

실제 문서를 보면 openApi.setInfo() 작업에서 명시된 이름이 실제 위에 표시되는 것을 볼 수 있다.

(3) Tag

1) @Tag

한 화면에 존재하는 API 들이 UserController, BoardContoller, GroupController 이름으로 나뉘는 것은 Tag 에 따라 한번 더 구별되기 때문이다.

@RestController
@RequestMapping("/api/v2/user")
@Tag(name = "UserController", description = "그룹 API")
public class SwaggerUserController {

    @GetMapping("/userApi1")
    public String userApi1() {
        return "index";
    }

    ...

}

위와 같이 Controller 단에서 Tag 를 설정하면 이하 모든 API 들은 해당 Tag 에 속하게 된다.

2) @Operation

@RestController
@RequestMapping("/api/v2/user")
@Tag(name = "BoardController", description = "게시판 API")
public class SwaggerBoardController {

    @GetMapping("/boardApi1")
    public String boardApi1() {
        return "index";
    }

    @GetMapping("/boardApi2")
    @Operation(summary = "hello API", description = "hello API 입니다.", tags = "GroupController")
    public String boardApi2() {
        return "hello";
    }
    @GetMapping("/boardApi3")
    @Operation(summary = "world API", description = "world API 입니다.", tags = "UserController")
    public String boardApi3() {
        return "world";
    }
}

만약 메서드 단에서 Tag 를 설정한다면 해당 메서드는 해당 Tag 를 가진다.
위처럼 Controller 단과 메서드 단에 태그가 각각 존재한다면 해당 메서드는 두 가지 태그를 모두 가진다.
boardApi3() 는 BoardController, UserController 태그를 동시에 가진다는 뜻이다.

실제 문서를 확인하면

우선 UserController 태그에는 userApi 전부와 boardApi3() 가 존재했다.

여기서 내가 헷갈린 점은 BoardController 의 다른 메서드들의 존재 여부였다. 하지만 간단하게 "/user" path 를 쓰기에 당연하게 존재하는 것이다. tag 와 group 구분을 확실하게 하도록 하자.

boardApi2() 메서드는 GroupController 와 BoardController 두 개의 태그가 존재하기에 두 곳에서 확인할 수 있다.

메서드의 Operation 태그에 들어가는 것들은 API 에 대한 설명이다. 이를 해당 화면에서도 확인할 수 있다!

(4) Schema

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
@Tag(name = "Dto Name", description = "Description of SwaggerDto API")
public class SwaggerDto {
    @Schema(title = "이름", description = "이름을 작성", example = "min9805")
    private String name;

    @Schema(title = "나이", description = "나이를 작성", example = "27")
    private int age;
}

위와 같은 Dto 를 생성했다고 가정하자. 각 필드에 @Schema 를 생성해 설명과 example 을 설정할 수 있다.

작성한 @Schema 는 위와 같이 확인할 수 있다.

각 API 에서 Dto 를 사용한다면 예시에 example 에 넣은 값들이 들어가고 나오는 것도 확인할 수 있다.

여기서 메서드 @Operation 의 설정값들이 자세하게 나오는 것도 확인할 수 있다.

4. 결론

Swagger 같이 편리한 툴은 잘 작성해서 제대로 사용하자!

Github Code