[Spring Boot] REST API 명세 문서화하기 - Swagger

본 내용은 Spring Boot 2.x 버전에서 유효함

Swagger

: 애플리케이션의 REST API 문서를 자동으로 구성해주는 도구

---

의존성 추가

1. maven -> pom.xml 내에 추가

<dependencies>
	...(생략)...

	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.9.2</version>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.9.2</version>
	</dependency>
</dependencies>

2. gradle -> build.gradle 내에 추가

dependencies {
    implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2' // swagger
	implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2' //swagger
}

Swagger 설정

• config/SwaggerConfiguration.java를 생성 후 기본 설정 완료하기

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket restAPI() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("therapia.farm"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Therapia API")
                .version("1.0.0")
                .description("농장 커뮤니티 및 작물 진단 서비스 Therapia의 API 문서입니다.")
                .build();
    }
}

Swagger에서 스캔할 패키지 범위를 RequestHandlerSelectors.basePackage('therapia.farm')로 입력하여 해당 하위 패키지와 클래스를 모두 스캔하여 문서화하였다.

기존 코드에 적용 (Swagger 명세를 추가)

• API 그룹 설정 (Controller에 Api 어노테이션 추가)

@Api(tags = {"Crop API"})  // Crop API 그룹으로 설정
@Log4j2
@RestController
@RequiredArgsConstructor
public class CropApiController {
	...
}

• API 상세 정보 설정 (ApiOperation 어노테이션 추가)

@ApiOperation(value = "모든 작물 가져오기", notes = "모든 작물 List 가져오기")
@GetMapping("/api/crops")
public ResponseEntity<List<CropDto>> cropList(){
    return new ResponseEntity<>(cropService.findCrops(), HttpStatus.OK);
}

@ApiOperation(value = "개별 작물 가져오기", notes = "작물 ID로 작물 가져오기")
@GetMapping("/api/crops/{cropId}")
public ResponseEntity<CropDto> cropById(@PathVariable("cropId") Long cropId){
    return new ResponseEntity<>(cropService.findById(cropId), HttpStatus.OK);
}

• 매개변수에 대한 설명 (매개변수에 ApiParam 어노테이션 추가)

@GetMapping(value = "/request1")
@ApiOperation(value = "GET 메소드 예제", notes = "@RequestParam을 활용한 GET Method")
public String getRequestParam(
        @ApiParam(value = "이름", required = true) @RequestParam String name,
        @ApiParam(value = "이메일", required = true) @RequestParam String email,
        @ApiParam(value = "회사", required = true) @RequestParam String organization) {
    ...(생략)...
}

---

Swagger 문서 확인 및 통신 테스트