Support @Schema annotations on Kotlin value classes #3168
Description
Is your feature request related to a problem? Please describe.
When using Kotlin value classes with @Schema annotations, SpringDoc does not recognize or apply the schema metadata (description, pattern, example, etc.) to the
generated OpenAPI specification.
For example, I have defined a value class like this:
@Schema(description = "Office ID", pattern = "^[0-9A-HJKMNP-TV-Z]{26}\$")
@JvmInline
value class OfficeId(private val value: String)And use it in a controller as a path parameter:
@RestController
class OfficeController {
@GetMapping("/v1/offices/{officeId}")
suspend fun getOffice(@PathVariable officeId: OfficeId): OfficeResponse {
...However, the actual result in the OpenAPI specification is:
parameters:
- name: officeId
in: path
required: true
schema:
type: stringThe @Schema annotation's description and pattern attributes are completely ignored.
Describe the solution you'd like
SpringDoc should respect @Schema annotations on Kotlin value classes and include the metadata in the generated OpenAPI specification. This would eliminate the need to duplicate descriptions, patterns, and examples across every controller method.
The expected result should be:
parameters:
- name: officeId
in: path
description: Office ID
required: true
schema:
type: string
pattern: ^[0-9A-HJKMNP-TV-Z]{26}$Describe alternatives you've considered
Current workarounds include:
- Adding
@Parameterannotations directly on controller method parameters (requires duplication across all endpoints, violates DRY principle) - Using
@Schema(ref = ...)to reference a shared schema definition (adds complexity and indirection)
None of these alternatives are ideal as they sacrifice either type safety, performance, or maintainability.
Additional context