OpenAPITools / OpenAPITools/openapi-generator
[BUG][KOTLIN-CLIENT] OAS 3.x: Default enum value rendered without stating the enum name as query param
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Bug Report Checklist
- Have you provided a full/minimal spec to reproduce the issue?
- Have you validated the input using an OpenAPI validator?
- Have you tested with the latest master to confirm the issue still exists?
- Have you searched for related issues/PRs?
- What's the actual output vs expected output?
- [Optional] Sponsorship to speed up the bug fix or feature request (example)
Description
Goal: I want to $ref(erence) to defined parameters when defining query parameters for REST endpoints.
For that I use components/parameters. The param might be an optional enum with a default value.
Expected: When referencing to either components/parameters or at endpoint to its components/schema, the default enum value should be set.
Actual: the enum value is rendered without the enum class name, yielding a compile error.
Both OAS 3.0.3 and 3.1.0 are affected.
openapi-generator version
id("org.openapi.generator") version "7.12.0"
OpenAPI declaration file content or url
openapi: 3.0.3
info:
title: My service
description: My service
version: 1.0.0
servers:
- url: 'https://app.com/api/v1'
components:
parameters:
DocumentFormatParameter:
in: query
name: format
schema:
$ref: '#/components/schemas/DocumentFormat'
schemas:
DocumentFormat:
title: Document Format
type: string
enum: [ PDF, JSON ]
default: PDF
paths:
/hello:
get:
operationId: getHello
parameters:
- $ref: '#/components/parameters/DocumentFormatParameter' # renders to 'format: DocumentFormat? = PDF'
- in: query
name: format2
schema:
$ref: '#/components/schemas/DocumentFormat' # renders to 'format2: DocumentFormat? = PDF'
- name: format3
in: query
schema:
title: Title # this title is ignored, instead: 'Format3GetHello'
type: string
enum:
- PDF
- JSON
default: PDF # renders to 'Format3GetHello.PDF'
responses:
200:
description: OK
Generation Details
openApiGenerate {
generatorName.set("kotlin")
inputSpec.set("$projectDir/src/main/resources/openapi.yaml")
outputDir.set("$buildDir/generated")
apiPackage.set("com.example.api")
modelPackage.set("com.example.model")
library.set("jvm-retrofit2")
configOptions.set(
mapOf(
"dateLibrary" to "java8",
"enumPropertyNaming" to "original",
"serializationLibrary" to "jackson",
"useCoroutines" to "true",
),
)
}
Steps to reproduce
Take the openapi.yaml and generate code. See resulting DefaultApi.kt file.
See the comments in example OAS on where it goes all wrong.
@GET("hello")
suspend fun getHello(@Query("format") format: DocumentFormat? = PDF, @Query("format2") format2: DocumentFormat? = PDF, @Query("format3") format3: Format3GetHello? = Format3GetHello.PDF): Response<Unit>
Related issues/PRs
Suggest a fix
I think the culprit is within the mustache file modules/openapi-generator/src/main/resources/kotlin-client/param_default_value.mustache where we always include the OperationId as a prefix for the default enum value.
Instead the name of referenced schema enum should be taken into account.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with modules/openapi-generator/src/main/resources/kotlin-client/param_default_value.mustache and compare its output with the generated DefaultApi.kt from the provided openapi.yaml. Run the Kotlin client generation using the stated configuration, then verify that defaults for referenced and inline enum query parameters compile with the appropriate enum name.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin, openapi
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100