Swagger

hoyong.eom·2024년 9월 29일

Swagger

스프링

목록 보기

57/59

Swagger

오늘은 토이프로젝트에 swagger를 적용해보려고 한다.
swagger를 적용하는 이유는 구글링 해보면 여러 가지 이유들이 있다.

API 명세 자동화
API 테스트

나 같은 경우 토이 프로젝트이기 때문에 매번 postman이 아닌 swagger를 이용하기 위해서 적용을 해보았다.

설정

build.gradle 의존성 추가

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

구글링을 해보면서 springdoc이 아닌 springfox를 사용하는 경우도 있는데 srping 3.x 버전부터는 springfox가 아닌 springdoc을 사용해야 swagger를 사용할 수 있다고 한다.

참고) https://twojun-space.tistory.com/201

Config 추가

@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "Traffic Project",
                description = "버스, 지하철, 교통 신호 관리 프로젝트입니다."
        )
)
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi busStopApi() {
        return GroupedOpenApi
                .builder()
                .group("API-버스정류장")
                .pathsToMatch("/api/busstops/*")
                .build();
    }

    @Bean
    public GroupedOpenApi subWayApi() {
        return GroupedOpenApi
                .builder()
                .group("API-지하철")
                .pathsToMatch("/subway/*")
                .build();
    }

}

@OpenAPIDefinition : swagger-ui/index.html에서 화면 제목과 설명 내용을 추가합니다.

GroupOpenAPI : API를 그룹으로 묶어 UI에서 확인할 수 있도록 합니다.

@Tag : Controller 제목과 설명을 추가합니다.

@Tag(name = "BusStop", description = "BusStop API")
@RestController
@RequiredArgsConstructor
@Slf4j
public class BusStopController {

@Operation : API 액션을 정의하고, 액션 대한 추가 속성을 정의하는 데 사용합니다.
@ApiResponse : Operation에서 정의한 액션에 대한 Response를 정의합니다.
@Content : 특정 미디어 유형에 대한 스키마와 예를 제공합니다.
@Schema : 입력 및 출력 데이터를 정의할 수 있습니다.


    /**
     * v2. openAPI로 버스 정류장 정보 조회
     * @return
     */
    @Operation(summary = "버스 정류장 목록 조회", description = "v2. 버스 정류장 목록을 조회합니다.",
            responses = {
                @ApiResponse(description = "openAPI 버스 정류장 조회",
                        content = @Content(
                                mediaType = "application/json",
                                schema = @Schema(implementation = BusStop.class)
                        )
                )
            }
    )