[Spring] Custom Enum Value 를 Swagger 문서에 노출시키고 싶으면 어떻게 해야할까?

발단

swagger 를 통해 서버의 문서를 작성하던 중 Enum 타입으로 정의한 값을 제공하려 할 때 의도한 값이 문서에 노출되지 않고 Enum 으로 정의했던 변수의 이름이 노출되고 있어 이를 수정하기 위해 시도하였습니다.

 

 

라이브러리 문서

• 문서를 통해 enum 에 대한 값을 변화하는 기능은 현재 제공하고 있지 않은듯 합니다.

OpenAPI 3 Library for spring-boot

 

---

코드

enum class TestEnumType(
    val code: String
) {
    TEST1("t1"),
    TEST2("t2");
}

---

data class TestReqDto(
    val testEnumType: TestEnumType
)

---

@RestController
@RequestMapping("/api/v1/swagger-test")
@Tag(name = "테스트 용도")
class SwaggerTestServer {

    @PostMapping("")
    fun post1(
        @RequestBody testReqDto: TestReqDto
    ) {
        val breakPnt = ""
    }
}

 

---

Enum 노출값을 변경하기 위해 시도한 기능들

 

Schema

• 라이브러리에서 제공하는 annotation 으로 필드의 속성에 대해 자세히 명시할 수 있습니다. 
  • 예를들어, 설명(description), 기본 값(defaultValue), ..

 

allowableValues

• Schema 에 속하는 프로퍼티중 하나로 가능한 값들을 명시합니다.
• 해결 불가: 멤버변수를 비롯해 입력한 값들이 추가됩니다.
  • 위 사진에서는 allowableValues 로 t1, t2 를 추가한 상태입니다.

 

example

• Schema 에 속하는 프로퍼티중 하나로 예시로 제공되는 값을 뜻합니다.
• 해결 불가: 역시 위의 시진과 같이 값이 변하지 않습니다.

 

그외(defaultValue, description, title..)

• 속성 자체로는 의미가 없지만 혹시나 값이 변경될까 싶어 이것저것 적용해보았습니다.
• 해결 불가: `혹시가 역시나`로 원하는대로 값이 변하지 않았습니다.

---

Jackson 이 있어야 동작하는 open api?

GitHub - swagger-api/swagger-core: Examples and server integrations for generating the Swagger API Specification, which enables

 

swagger-core github 페이지를 살펴보던 중 Prerequisites(필요조건)을 보았는데 Jackson 을 필요로 한다는 것을 알게 되었습니다. 

 

해결방법

• 위에서 swagger-api 가 Jackson 을 필요로 한다는 것을 알게 되었고, api 를 노출할 때 직렬화 방식으로 사용되지 않을 까 싶어 JsonProperty annotation 을 사용해보기로 하였습니다.
• JsonProperty 는 간단히 말해서 json 의 속성을 조작하는 용도로 직렬화/역직렬화 하는 과정에서 Jackson 이 참조하게 되는 속성이 됩니다.

 

JsonProperty annotation 사용으로 해결

 

// enum 에 JsonProperty 적용
enum class TestEnumType(
    val code: String
) {
    @JsonProperty("t1") TEST1("t1"),
    TEST2("t2");
}

// ../v3/api-docs 스웨거 문서 확인
...
"properties": {
  "testEnumType": {
    "type": "string",
    "enum": [
      "t1", // t1 으로 속성값을 가진걸 알 수 있다.
      "TEST2"
    ]
  }
}
...

 

• `t1` 은 JsonProperty 를 명시하여 속성이 바뀐것을 알 수 있습니다. 반면 `TEST2` 는 명시하지 않아 변수명 그대로 직렬화되어 노출되고 있습니다.
• 또 swagger 의 문서에 명시된 dto 를 통해 알 수 있듯이 `TEST1` 속성이 `t1` 로 전환된것을 확인할 수 있습니다.