Swagger 3.0

파이썬 flask에서만 swagger를 써봤어서

스프링에도 자유자재로 사용하게끔 공부해봤습니다.

지금 어떤 이유인지는 모르겠는데
Issue

• 스프링 버전 2.6.3 에서 Swagger2 의존성 추가할 시
  호환이 안되서 스프링 버전을 2.5.6으로 낮추었다.

의존성 추가

이런식으로 추가 할수도 있지만

implementation("io.springfox:springfox-swagger2:2.9.2")
implementation("io.springfox:springfox-swagger-ui:2.9.2")

springfox 공식 github에서 밑에 처럼 쓰라고 권장하고 있다.
참고 : https://github.com/springfox/springfox

implementation("io.springfox:springfox-boot-starter:3.0.0")

Swagger URL
Swagger 버전에 따라 API 문서를 볼 수 있는 URL이 다르다. ( URL 때문에 시간 소요 많이 한듯 )

* Swagger 버전에 따른 URL 체크* 
2.X.X  :  http://localhost:8080/swagger-ui.html
3.X.X  :  http://localhost:8080/swagger-ui/index.html

SwaggerConfig.kt

@Configuration
@EnableSwagger2
class SwaggerConfig {
    @Bean
    fun restAPI() : Docket {
        return Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.any())    // 모든 RequestMapping URI 추출
            // .apis(RequestHandlerSelectors.basePackage("com."))   // 패키지 기준 추출
            // .paths(PathSelectors.ant("/v2/**")) // 경로 패턴 URI만 추출
            .paths(PathSelectors.any())
            .build()
            // .useDefaultResponseMessages(false)  // Response 응답 메시지 디폴트값 적용 X
    }

    private fun apiInfo() : ApiInfo {
        return ApiInfoBuilder()
            .title("Panda의 Spring boot Rest API 공부")
            .version("1.0.0")
            .termsOfServiceUrl("서비스 약관 url")
            .license("MIT")
            .licenseUrl("http://license.com")
            .description("Spring boot swagger api 구현 공부용입니다.")
            .contact(
                Contact(
                    "Contect us",
                    "연락할 주소",
                    "이메일")
            )
            .build()
    }
}

위와 같이 설정을 해주었다.
참고로 위의 옵션들 말고 여러가지가 더 있는데 필요하다면 추가옵션(설명)을 붙여도 될 것 같다.

Controller.kt

@Controller
class HelloController {

    @GetMapping("hello")
    @ApiOperation(value = "hello index 페이지", notes = "hello spring return")
    fun hello(model : Model) : String {
        model.addAttribute("data", "spring!!")
        return "hello"
    }

    @GetMapping("hello-mvc")
    @ApiOperation(value = "hello mvc", notes = "hello name return")
    fun helloMvc(@RequestParam("name") name : String, model : Model) : String {
        model.addAttribute("name", name)
        return "hello-template"
    }

    @GetMapping("hello-string")
    @ApiOperation(value = "hello string", notes = "hello name return")
    @ResponseBody
    fun helloString(name : String) : String = "Hello $name"

    @GetMapping("hello-api")
    @ApiOperation(value = "hello api", notes = "hello name return")
    @ApiResponses( value = [
        ApiResponse(code = 200, message = "ok"),
        ApiResponse(code = 404, message = "page not found!")
    ])
    @ResponseBody
    fun helloApi(@RequestParam("name") name : String) : Hello {
        val hello = Hello(name)
        
        return hello
    }

    class Hello(val name : String) {
         
    }
}

간단하게
@ApiOperation, @ApiResponses 로 구현을 해봤다.

flask Swagger를 썻을때보다 자동으로 entry point가 등록이 되서 훨씬 편했다.

@ApiResponses를 구글링하여 작성하면서 밑에와 같이 작성했는데
컴파일 에러가 계속 존재하였다.... 따라서 기존 코드와 같이 문법을 수정을 하였다.

@ApiResponses({
	@ApiResponse(code = 200, message = "ok"),
    @ApiResponse(code = 404, message = "page not found!")
})

결과 사진

위와 같이 Swagger를 이용해서 API 문서 틀을 만들어 보았다.

다양한 Swagger Annotation이 존재하는데
필요하다면 공부해서 사용하면 될 것 같다.