[Spring] Swagger로 API 문서 자동화하기

Swagger

 

• REST API를 설계, 빌드, 문서화 및 사용하는 데 도움이 되는 OpenAPI 사양을 중심으로 구축된 오픈 소스 도구 세트
• Spring REST Docs보다 Swagger은 적용하기 훨씬 쉽다 그리고 이쁘다 (이쁘면 다야)
• Spring REST Docs는 테스트를 돌리면서 성공하는지 실패하는지를 확인하지만 Swagger은 문서 화면에서 API를 바로 테스트 할 수 있다
• 따라서 Spring REST Docs의 장점, Swagger의 장점만 뽑아 둘이 같이 사용한다고 한다

 

 

 

1. dependency 추가 (gradle)

 

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

 

 

2. 설정 세팅

 

@Configuration
@EnableSwagger2
public class SwaggerConfig {

   @Bean
   public Docket api(){
      return new Docket(DocumentationType.SWAGGER_2)
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
         .paths(PathSelectors.any()) // .ant("/create/**")로 선택 가능
         .build().apiInfo(apiInfo());
   }

   private ApiInfo apiInfo(){
      return new ApiInfoBuilder()
         .title("프로젝트명")
         .description("프로젝트 설명")
         .version("1.0")
         .build();
   }

}

 

 

3. 컨트롤러에 가서 어노테이션 붙여주기

 

@ApiOperation("선택한 기간 중의 모든 일기 데이터를 가져옵니다")
@GetMapping("/read/diaries")
List<Diary> readDiaries(
   @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
   @ApiParam(value = "날짜 형식 : 조회할 기간의 첫 번째 날", example = "2020-02-02") LocalDate startDate,
   @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
   @ApiParam(value = "날짜 형식 : 조회할 기간의 마지막 날", example = "2020-02-02") LocalDate endDate) {
   return diaryService.readDiaries(startDate, endDate);
}

• 나의 프젝 컨트롤러 중 GET /read/diaries 예시
• @ApiOperation(value = "api 요약란", notes = "api 설명란")
• @ApiParam(name="파라미터 이름", value = "파라미터 설명", example = "파라미터 예시")

 

 

4. 결과 예시 ~ (localhost:8080/swagger-ui/index.html#)

 

 

 

 

자세한 설명 : https://velog.io/@banjjoknim/Swagger