스프링 Ch 9 Swagger/OpenAPI - 패스트캠퍼스 챌린지 15일차

앗싸 오늘거 실습 필요 없다 실습당했다

Swagger 입니다. 지금은 OpenAPI 랑 반반무마니 해서 갈라지긴 했는데 아무튼 API를 예쁘게 표준에 맞춰서 json 형식으로 문서화해주고, 클라이언트까지 알아서 만들어주는 편리한 친구입니다.

그런데 강의에서 제가 몰랐던 새로운 활용법을 알려주더라구요? 바로 /swagger-ui 페이지에서 마치 Postman 같은 거에서 실행해보듯이 바로 테스트를 해볼 수 있다는 것이었습니다. 이건 살짝 충격~

사용하는 라이브러리

https://github.com/springfox/springfox

springfox 프로젝트를 사용합니다. 기존 라이브러리(라는 게 있는지도 몰랐지만)들은 어노테이션을 수동으로 달아야 했지만, springfox 프로젝트를 사용하면 알아서 자동으로 모든 API가 공개되게 된답니다. 어차피 공개할거면 편하겠네요!

강의에서는 springfox-swagger2 를 사용하지만, springfox github 페이지에서는 그거 빼고 springfox-boot-starter 을 추가하길 권고하고 있습니다. 마이그레이션 가이드까지 있네요.

@EnableWebMvc 어노테이션이 있어야 에러가 나지 않습니다 (springfox github 의 마이그레이션 섹션 참조). 이유는 모르겠는데 메인 앱에 붙여도 되더라구요? 물론 전 별도의 컨피그에.

@Configuration
@EnableWebMvc
class WebMvcConf: WebMvcConfigurer {
}

http://localhost:8080/swagger-ui/index.html

어노테이션

springfox 를 사용하면 모든 API가 공개되기는 하지만, 설명은 빠져있습니다. 설명은 어노테이션으로 넣어야 합니다.

• @Api( tags = { "섹션 제목" })
  

  • @Api(tags = ["계산기", "계산을 합니다"])
    @RestController
    @RequestMapping("/api/v1/calc")
    class CalcHandler(

• @ApiParam - API 패러미터에 문서화

  •     fun plus(...
                 @ApiParam("dummy값", defaultValue = "0")
                 @RequestParam dummy: Int = 0): Int {

• @ApiOperation - 핸들러 자체에 설명을 붙입니다.
  @ApiResponse - 핸들러의 응답을 문서화합니다. HTTP 코드를 달아서 설명을 붙일 수 있음

  •     @PutMapping("/add")
        @ApiResponse(code=444, message = "잭팟!")
        @ApiOperation("두 값을 더합니다", tags=["계산"])
        fun add(@RequestBody values: CalcValuesDto): CalcResultDto {

• @ApiImplicitParams 및 @ApiImplicitParam - 패러미터에 직접 어노테이션을 달자니 주렁주렁해질 때 핸들러 위에 답니다.

  •     @ApiImplicitParams(
            ApiImplicitParam(name = "x", value = "X값", required = true, paramType = "query", dataType = "int"),
            ApiImplicitParam(name = "y", value = "Y값", required = true, paramType = "path", dataType = "int")
        )
        @GetMapping("/plus/{y}")
        fun plus(@RequestParam x: Int, @PathVariable y: Int,

• @ApiModelProperty - Dto 같은 데이터 필드에 달아두면 됩니다.

  • data class CalcValuesDto(
        @ApiModelProperty("값 1", example = "123")
        val v1: Float,
        @ApiModelProperty("값 1", example = "456")
        val v2: Float
    )

전체 코드

@Api(tags = ["계산기", "계산을 합니다"])
@RestController
@RequestMapping("/api/v1/calc")
class CalcHandler(
    private val calculator: CalcService,
    private val sayHelloService: SayHelloService
) {
    @ApiImplicitParams(
        ApiImplicitParam(name = "x", value = "X값", required = true, paramType = "query", dataType = "int"),
        ApiImplicitParam(name = "y", value = "Y값", required = true, paramType = "path", dataType = "int")
    )
    @GetMapping("/plus/{y}")
    fun plus(@RequestParam x: Int, @PathVariable y: Int,
             @ApiParam("dummy값", defaultValue = "0")
             @RequestParam dummy: Int = 0): Int {
        return x + y
    }
    @PutMapping("/add")
    @ApiResponse(code=444, message = "잭팟!")
    @ApiOperation("두 값을 더합니다", tags=["계산"])
    fun add(@RequestBody values: CalcValuesDto): CalcResultDto {
        return CalcResultDto(calculator.add(values.v1, values.v2))
    }
}

data class CalcValuesDto(
    @ApiModelProperty("값 1", example = "123")
    val v1: Float,
    @ApiModelProperty("값 1", example = "456")
    val v2: Float
)

---

실습을 안 해보려고 했는데 결국 해보게 되네요. 그 과정에서 사소한 트러블슈팅이 있었습니다. 뭐 어차피 문서화야 필요할 때 하면 되는거니까요.

본 포스팅은 패스트캠퍼스 환급 챌린지 참여를 위해 작성되었습니다.
패스트캠퍼스: https://bit.ly/37BpXiC

#패스트캠퍼스 #패캠챌린지 #직장인인강 #직장인자기계발 #패스트캠퍼스후기 #한번에끝내는JavaSpring웹개발마스터초격차패키지Online

내일은 드디어 진짜 프로젝트네요... 근데 DB 없이 어떻게 하지? 했더니 목차를 보니 Memory CRUD DB 랍니다. 그럼 인정이지.