Skip to content

Enable automatic Kotlin Nullability in Swagger#29

Merged
jeyongsong merged 2 commits intomainfrom
swagger-nullable
Feb 22, 2026
Merged

Enable automatic Kotlin Nullability in Swagger#29
jeyongsong merged 2 commits intomainfrom
swagger-nullable

Conversation

@jeyongsong
Copy link
Member

This pull request primarily removes unnecessary Swagger annotations and validation imports from several DTO classes to streamline the codebase and reduce clutter. No functional changes to business logic or data handling are introduced.

Cleanup of DTO classes:

  • Removed @Schema(nullable = true) Swagger annotations from fields in HomeResponse, WorkdayResponse, and OnboardingStatusResponse to simplify the DTOs and reduce external dependencies. [1] [2] [3]
  • Removed unused validation imports (@Min, @Max) from PaydayUpdateRequest since these annotations are not used in the class.

General code simplification:

  • Cleaned up formatting in WorkPolicyUpsertRequest by removing an unnecessary line break.

@jeyongsong
Copy link
Member Author

jeyongsong commented Feb 22, 2026

@subsub97 참고하세용~~

1. 역할 분담: 누가 무엇을 하는가?

Swagger가 문서를 만드는 과정은 보통 다음과 같은 흐름을 거칩니다.

Jackson: 코틀린 클래스를 분석해서 어떤 필드가 있는지, 어떤 필드가 비어있어도 되는지(Nullable) 등을 파악하여 JSON 구조를 설계합니다.

SpringDoc (Swagger): Jackson이 분석해놓은 그 설계도(객체 모델)를 가로채서 웹 화면(Swagger UI)에 예쁘게 그려줍니다.

2. jackson-module-kotlin이 없으면 발생하는 일

자바는 기본적으로 모든 참조 타입이 null이 될 수 있습니다. 하지만 코틀린은 String과 String?을 명확히 구분하죠.

표준 Jackson 라이브러리는 자바 기반이라서 코틀린의 **"이 변수는 절대 null이 되면 안 돼!"**라는 정보를 읽지 못합니다. 그래서 모든 필드를 "있어도 그만, 없어도 그만"인 것으로 취급해 버립니다.

3. jackson-module-kotlin이 해주는 일

이 모듈이 추가되면 Jackson에게 **"코틀린 전용 안경"**을 씌워주는 것과 같습니다. 이 안경을 쓰면 비로소 다음을 인식합니다.

Non-nullable 필드 인식: val name: String을 보면 "아, 이건 JSON 데이터에 무조건 있어야 하는 필수(Required) 값이구나!"라고 판단합니다.

Nullable 필드 인식: val age: Int?를 보면 "이건 null이어도 되니까 필수가 아니네(Optional)!"라고 판단합니다.

Default Value 인식: val role: String = "USER" 같은 기본값을 읽어서 Swagger 문서의 기본값 항목에 자동으로 넣어줍니다.

@github-actions
Copy link

Test Results

32 tests   32 ✅  0s ⏱️
 3 suites   0 💤
 3 files     0 ❌

Results for commit b5087ab.

@jeyongsong jeyongsong merged commit 9fdb161 into main Feb 22, 2026
2 checks passed
@jeyongsong jeyongsong deleted the swagger-nullable branch February 22, 2026 11:33
@subsub97
Copy link
Collaborator

덕분에 많이 배웁니다~~

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants