Swagger 사용

Swagger 란 ?

REST API 스펙 명세 및 관리가 목적으로 하는 Open Api Specification(OAS)를 위한 프레임워크

Swagger 설정

implementation "org.springdoc:springdoc-openapi-ui:1.6.9"

build.gradle 파일에 의존성 추가

SwaggerConfig.java 파일 생성

@OpenAPIDefinition(
        info = @Info(title = "API 명세서",
                description = "API 명세서 테스트 입니다.",
                version = "v1"))
                
@Configuration
@RequiredArgsConstructor
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi publicAPi(){

        return GroupedOpenApi.builder()
                .group("v1-definition")
                .pathsToMatch("/api/**")
                .build();
    }
}

@OpenAPIDefinition 을 통해 다음 그림과 같이 설명을 적어준다.

SwaggerConfig.class 를 통해 group 및 path 등을 지정해줄 수 있다.

Swagger 기능

TestController

@RestController
@RequiredArgsConstructor
public class TestController {
    @Operation(summary = "get_test" , description = "get test 샘플 예제")
    @ApiResponses({
            @ApiResponse(responseCode = "200" , description = "OK!"),
            @ApiResponse(responseCode = "400" , description = "Bad Request"),
            @ApiResponse(responseCode = "404" , description = "NOT FOUND"),
            @ApiResponse(responseCode = "500" , description = "INTERNAL SERVER ERROR!!")
    })
    @GetMapping("/api/get/test")
    public ResponseEntity<String> hello(
            @Parameter(description = "이름", required = true, example = "김민엽") @RequestParam String name,
            @Parameter(description = "나이", example = "25") @RequestParam int age
    ) {
        return ResponseEntity.ok("안녕하세요. "+age+"살 "+name+"님");
    }

    @Operation(summary = "post_test" , description = "post test 샘플 예제")
    @ApiResponses({
            @ApiResponse(responseCode = "200" , description = "OK!"),
            @ApiResponse(responseCode = "400" , description = "Bad Request"),
            @ApiResponse(responseCode = "404" , description = "NOT FOUND"),
            @ApiResponse(responseCode = "500" , description = "INTERNAL SERVER ERROR!!")
    })
    @PostMapping("/api/post/test")
    public ResponseEntity testMessage(@RequestBody TestDTO testDTO){
        return ResponseEntity.ok().build();
    }
}

다음과 같이 test 컨트롤러 하나 만들어준다.(TestDTO도 만들어줌)

• @Operation 해당 API 에 대한 정보
• @ApiReposnses response 에 대한 정보로 여러개의 @ApiResponse 를 가지고 있다
• @ApiResponse response 코드와 설명을 설정
• @Parameter 파라미터에 대한 정보

localhost:8080/swagger-ui.html 에 접속하면 다음과 같이 명세된 API 정보를 조회할 수 있다.

참고 자료
https://jjingho.tistory.com/8
https://velog.io/@cho876/API-Swagger-%EC%82%AC%EC%9A%A9%EB%B2%95