[Spring boot] Swagger API 연동하기

이정규·2022년 3월 8일

Spring Boot 2.6.4
Java 11

Swagger 설정하는 방법

Swagger설정하기 위한 라이브러리는 2가지가 있다.
Spring-Fox, Spring-Doc 2가지 중에 사용하면 된다.

Spring-Fox
- 오래전에 나온 라이브러리이다. (2015년)
- 2020년 이후로 업데이트가 멈췄다.
- 그래서 Spring Boot 2.6이상 버전에서는 바로 적용이 안된다.

https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

Spring-Doc
- 최근에 나온 라이브러리이다. (2019년)
- 업데이트가 최근까지도 이루어지고 있다.
- Spring boot 2.6이상도 지원한다.

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

초기에는 Spring-fox를 이용하여 설정하였는데, 설정하는 방법이 WebMVC Configuration을 직접 건드리는 것이여서 추후에 문제가 생길것도 하여 Spring-doc으로 다시 되돌아왔다.

Spring-fox는 업데이트가 더 이상 이루어지지 않아 쓰이지 않는 분위기이다. 그래서 Spring-doc을 설정하는 방법에 대해 설명하고자 한다.

Gradle 설정하기

implementation 'org.springdoc:springdoc-openapi-ui:1.6.6'

제일 최근 버전을 사용했다. 위에 적어둔 홈페이지로 가서 원하는 버전으로 설정하면 된다.

Config 파일 만들기

Swagger2Config.java

@Configuration
public class Swagger2Config {

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("v1-definition")
                .pathsToMatch("/api/**")
                .build();
    }
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Bstagram API")
                        .description("BMW 프로젝트 API 명세서입니다.")
                        .version("v0.0.1");
    }
}

group
- group 이름을 설정한다.
pathsToMatch
- Swagger API 명세서에 적을 API 주소를 적는다.
- "/api/**" 이라고 적는다면 "http://localhost:8080/api/~~" 로 시작하는 친구들을 다 매칭시킨다는 얘기이다.
OpenAPI
- Swagger API 명세서에 들어왔을 때 어떻게 보여줄 지 Customizing하는 부분이다.

더 많은 설정은 https://springdoc.org/#properties 여기서 확인 가능하다.

Controller 설정

@Tag(name = "posts", description = "게시물 API")
@RestController
@RequestMapping("/api/posts")
@RequiredArgsConstructor
public class PostsController {

    @Operation(summary = "get posts", description = "지역에 대한 posts들 가져오기")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = PostsResponseDto.class))),
            @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
            @ApiResponse(responseCode = "404", description = "NOT FOUND"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR")
    })
    @Parameters({
            @Parameter(name = "province", description = "시", example = "경기도"),
            @Parameter(name = "city", description = "도", example = "고양시"),
            @Parameter(name = "hashtag", description = "검색한 해시태그", example = "['#자장면', '#중국집']")
    })
    @ResponseBody
    @GetMapping( "")
    public PostsResponseDto getPosts(
            @RequestParam(value = "province") String province,
            @RequestParam(value = "city") String city,
            @RequestParam(value = "hashtag", required = false) @Nullable String hashtag
    ) {
        return new PostsResponseDto(1);
    }
}