Swagger UI 3.0 적용하여 편리하게 API 명세서 작성하기

[Swagger]

개발자들의 API 문서화를 쉽게 할 수 있도록 도와주며, 파라미터를 넣어서 실제로 어떤 응답이 오는지 테스트도 할 수 있습니다.

 

또한, 협업하는 클라이언트 개발자들에게도 Swagger 만 전달해주면 API Path 와 Request, Response 값 및 제약 등을 한번에 알려줄 수 있습니다.

 

의존성 추가(build.gradle)

//Swagger UI
    implementation 'io.springfox:springfox-boot-starter:3.0.0'

SwaggerConfig 추가

@Configuration
public class SwaggerConfig {

    private static final String API_NAME = "Post, Letter, Category API";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "Post, Letter, Category API 명세서";

    @Bean
    public Docket commonApi(){

        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.devthink.devthink_server.controllers"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(API_NAME)
                .version(API_VERSION)
                .description(API_DESCRIPTION)
                .build();
    }
}

• Docket: Swagger 설정의 핵심이 되는 Bean
• apis: api 스펙이 작성되어 있는 패키지 (Controller) 를 지정 가능하다
• paths: apis 에 있는 API 중 특정 path 를 선택
• apiInfo: Swagger UI 로 노출할 정보

apiInfo에 API_NAME, API_VERSION, API_DESCRIPTION을 보여줄수 있다.

필자는 config/SwaggerConfig.class에 저장했습니다.

 

[컨트롤러 추가]

@GetMapping("/best")
    @ApiOperation(value = "베스트 게시글 가져오기",
            notes = "사용자로부터 카테고리 id를 받아, 베스트 게시글을 가져옵니다.")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "categoryId", dataType = "Long", value = "카테고리 아이디")})
    public List<PostResponseData> searchBest(@RequestParam Long categoryId){
        Category category = categoryService.getCategory(categoryId);
        List<Post> bestPost = postService.getBestPost(categoryId);
        return getPostList(bestPost);
    }

@ApiOperation(value = "이름 설명", notes = "본문 설명") 
@ApiImplicitParams({name = "전달 파라미터 이름", dataType = "리턴 타입", value = "파라미터 설명")})

이런식으로 API에 대한 설명을 추가 가능하다.

 

 

이렇게 설정한 후 

http://localhost:8080/swagger-ui/index.html# 를 접속하면

 

Rest API를 Swagger를 통해 자동화 가능하다!