[JSCODE] 5회차

🎯 목표

• API 문서 작성

✏️ 내용

1. 게시글 전체 조회, 검색 기능 분리

이번 레벨 요구 사항에서 게시글 전체 조회 기능과 게시글 검색 기능이 각각 분리되어 있는 것을 보고 두 기능의 api를 분리하였다.

public List<Post> findAllPost() {
	return postRepository.findAll();
}

public List<Post> findAllPostByTitle(String keyword) {
	if (keyword.length() < 1) {
		throw new PostException(ErrorCode.BAD_REQUEST);
	}
	PostSearch postSearch = new PostSearch(keyword);
	return postRepository.findAllByTitle(postSearch);
}

2. 툴 선택

찾아보니 API 문서를 작성하기 위해 사용할 툴이 꽤 많았다.
Swagger, Notion, Postman 중에서 고민하다가 Swagger를 선택했다.
그 이유는 Notion의 경우 API 스펙이 변경되면 직접 모두 수정해야 하므로 귀찮아질 것 같아 제외했고, Postman은 어느정도 자동화 해주긴 하지만 마찬가지로 직접 작성할 부분이 꽤 존재했다.
그래서 자동으로 문서를 작성해주는 Swagger를 택했다.
무엇보다 많은 사람들이 사용한다는 것은 그만한 이유가 있다고 생각한다.

3. 의존성 추가

의존성을 추가하기 위해서 build.gradle 파일에 아래 코드를 추가하였다.

implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

4. SwaggerConfig 추가

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(true) // Swagger 에서 제공해주는 기본 응답 코드를 표시할 것이면 true
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("jscode.jscodestudy")) // Controller가 들어있는 패키지. 이 경로의 하위에 있는 api만 표시됨.
                .paths(PathSelectors.any()) // 위 패키지 안의 api 중 지정된 path만 보여줌. (any()로 설정 시 모든 api가 보여짐)
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot Rest API Documentation")
                .description("jscode 스터디에서 사용하는 API 문서입니다.")
                .version("0.1")
                .build();
    }
}

5. DTO에 Swagger 관련 애노테이션 추가

@Data
@ApiModel(value = "게시글 정보")
public class PostDto {

    @ApiModelProperty(name = "id", value = "아이디", example = "1", required = true, dataType = "Long")
    private Long id;

    @NotBlank(message = "제목은 공백 없이 1글자 이상 15글자 이하여야 합니다.")
    @Size(min = 1, max = 15, message = "제목은 공백 없이 1글자 이상 15글자 이하여야 합니다.")
    @ApiModelProperty(name = "title", value = "제목", example = "제목", required = true, dataType = "String")
    private String title;

    @NotEmpty(message = "내용은 1글자 이상 1000글자 이하여야 합니다.")
    @Size(min = 1, max = 1000, message = "내용은 1글자 이상 1000글자 이하여야 합니다.")
    @ApiModelProperty(name = "content", value = "내용", example = "내용", required = true, dataType = "String")
    private String content;

    @ApiModelProperty(name = "createdTime", value = "생성일자", required = true, dataType = "LocalDateTime")
    private LocalDateTime createdTime;

💬 회고

Swagger의 기본적인 개념과 이를 사용해서 어떻게 API 문서를 작성하는지 학습했다.
Swagger에는 springfox와 springdocs가 있다고 하는데, 나는 springfox를 사용했다.
Swagger 사용법을 익히면서 springdocs도 사용해서 다시 작성해볼 생각이다.