Spring - Swagger API 명세 작성

Swagger 의존성 추가 (Gradle) 
Swagger 설정 추가
API 그룹 설정
API 상세 정보 설정
API Data Schema
API Response

 

* 본 Swagger는 Spring 3.x Java 17에서 작성되었다.

 

Swagger

 

Swagger는 API 문서화 및 테스트 도구로서, 개발자가 RESTful API를 더 쉽게 문서화하고 API 엔드포인트를 테스트하고 이해할 수 있도록 돕는 오픈소스 프레임워크다. 1. API 스펙 정의 / 2. 자동 문서화의 장점이 있다.

 

Swagger 의존성 추가 (Gradle) 

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

 

Spring 3.x 버전에서는 위 코드를 Gradle에 추가해준다.

 

Swagger 설정 추가

 

- SwaggerConfig.java

@OpenAPIDefinition(
        info = @Info(
                title = "review API 명세서",
                description = "음식점 review 서비스 API 명세서",
                version = "v1"

        )
)
@Configuration
public class SwaggerConfig {
}

 

@OpenAPIDefinition : OpenAPI(이전의 Swagger) 스펙의 정의를 시작하는 데 사용된다. OpenAPI는 API 스펙을 정의하고 문서화하기 위한 표준이다.

info : API에 대한 정보를 제공하는 객체이다. title(명세서 이름), description(설명), version(명세서 버전)을 작성할 수 있다.

 

서버주소/swagger-ui/index.html

 

위 URL을 통해 Swagger에서 제공하는 명세서를 볼 수 있다.

 

 

API 그룹 설정

 

@Tag를 사용하여 해당 Controller 클래스에 대한 설명을 추가할 수 있다.

@RequiredArgsConstructor
@RestController
@Tag(name = "Restaurant 컨트롤러", description = "Restaurant API입니다.")
public class RestaurantApi {

    private final RestaurantService restaurantService;
    ...
    .....

 

API 상세 정보 설정

 

@Operation를 Controller 클래스 내부 Method 위에 작성하여 각 Method에 대한 설명을 추가할 수 있다. 

@RequiredArgsConstructor
@RestController
@Tag(name = "Restaurant 컨트롤러", description = "Restaurant API입니다.")
public class RestaurantApi {

    private final RestaurantService restaurantService;

    @Operation(summary = "Restaurant 조회", description = "사용자가 레스토랑 목록을 조회합니다.")
    @GetMapping("/restaurants")
    public List<RestaurantView> getRestaurants() {
        return restaurantService.getAllRestaurants();
    }

 

API Data Schema

 

data에 @Schema 어노테이션을 이용하여 해당 data가 어떤 Schema를 나타내고자 하는 것을 명시한다.

description : 해당 data가 어떤 data schema를 나타내는지 명시

nullable : null이 가능한지 아닌지 설정

example : 해당 data schema 예시 값 설정

@Getter
@AllArgsConstructor
public class CreateAndEditRestaurantRequest {

    @Schema(description = "음식점 이름 작성", nullable = false, example = "왕돈까스")
    private final String name;
    @Schema(description = "음식점 주소 작성", nullable = false, example = "서울 동작구")
    private final String address;
    private final List<CreateAndEditRestaurantRequestMenu> menus;
}

@Getter
@AllArgsConstructor
@NoArgsConstructor
public class CreateAndEditRestaurantRequestMenu {

    @Schema(description = "음식점 메뉴 이름 작성", example = "돈까스")
    private String name;
    @Schema(description = "음식점 메뉴 금액", example = "10000")
    private Integer price;

}

 

위 data들은 Request DTO에 해당한다. /restaurant POST에 사용되는 DTO들이며 위와 같이 @Schma 어노테이션을 이용하여 data에 필요한 정보들을 기입해준다.

 

 

위에서 @Schema를 통해 작성한 내용들이 Swagger를 통해 확인 가능한 것을 볼 수 있다.

 

API Response

 

@ApiResponses 어노테이션을 이용하여 API 요청에 대한 Response에 대해 설명하는 것이 가능하다.

ResponseCode : 반환되는 Response의 상태 코드를 나타낸다.

description : 반환되는 상태에 따라 어떤 상태, 결과인지 설명해준다.

content : 반환되는 데이터가 무엇인지 반환해준다.