OpenAPITools / OpenAPITools/openapi-generator

[BUG][KOTLIN-CLIENT] OAS 3.x: Default enum value rendered without stating the enum name as query param

Open
#21,437 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.