OpenAPITools / OpenAPITools/openapi-generator

[BUG] `example:` - List<String> and Map<String, XXX> doesn't create correct annotations (`spring`)

Open
#22,325 2 comments 0 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

I'm trying to generate examples for the array and additionalProperties. However, the @Schema(example="...") is incorrect.

  allSchemaIds:
    type: array
    items:
      type: string
    description: list of all the supported schemas in this system
    example:
        - iso19115-3.2018
        - iso19139

When using the spring generator, I get this annotation:

@Schema(name = "allSchemaIds", example = "[iso19115-3.2018, iso19139]", description = "list of all the supported schemas in this system", requiredMode = Schema.RequiredMode.NOT_REQUIRED)

When I request the openapi document from spring, I get this:

"allSchemaIds": {
            "type": "array",
            "description": "list of all the supported schemas in this system",
            "example": "[iso19115-3.2018, iso19139]",
            "items": {
              "type": "string",
              "description": "list of all the supported schemas in this system",
              "example": "[iso19115-3.2018, iso19139]",
              "xml": {
                "name": "allSchemaIds"
              }
            }
 },

I believe this should be "example": "[\"iso19115-3.2018\", \"iso19139\"]", or something similar.

For the map example:

  recordsPerSchema:
    type: object
    additionalProperties:
      type: integer
    description: map from the schemaId (schema name) to the number of records of that schema type in this system
    example:
      iso19115-3.2018: 4
      iso19139: 39

When using the spring generator, I get this annotation:

@Schema(name = "recordsPerSchema", example = "{iso19115-3.2018=4, iso19139=39}", description = "map from the schemaId (schema name) to the number of records of that schema type in this system", requiredMode = Schema.RequiredMode.NOT_REQUIRED)

This is incorrect. I think the key's need to be quoted and the = changed to a :

example = "{\"iso19115-3.2018\":4, \"iso19139\":39}"

I took a quick look at the moustache (https://github.com/OpenAPITools/openapi-generator/blob/d318752478b620b3b697b973f86a1a90dbc1acb1/modules/openapi-generator/src/main/resources/JavaSpring/pojo.mustache#L240) and I think its, probably, in the parsing or in how its going from the internal java object to string.

openapi-generator version

7.16.0

OpenAPI declaration file content or url

openapi-schema.zip

Generation Details
<build>
    <sourceDirectory>src/main/java</sourceDirectory>
    <plugins>
      <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>7.16.0</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <inputSpec>${project.basedir}/src/openapi-schema/workshop2-openapi.yaml</inputSpec>
              <generatorName>spring</generatorName>
              <generateAliasAsModel>true</generateAliasAsModel>
              <modelNamePrefix>Workshop2</modelNamePrefix>
              <modelNameSuffix>Dto</modelNameSuffix>
              <generateApiTests>false</generateApiTests>
              <generateModelTests>false</generateModelTests>
              <typeMappings></typeMappings>
              <configOptions>
                <sourceFolder>src/gen/java/main</sourceFolder>

                <interfaceOnly>true</interfaceOnly>

                <useJakartaEe>true</useJakartaEe>
                <useSpringBoot3>true</useSpringBoot3>
                <library>spring-boot</library>
                <useSpringfox>false</useSpringfox>

                <annotationLibrary>swagger2</annotationLibrary>
                <generateBuilders>true</generateBuilders>
                <withXml>true</withXml>
                <useOptional>false</useOptional>
                <!--                <openApiNullable>true</openApiNullable>-->

                <apiPackage>org.geonetwork.workshop2</apiPackage>
                <modelPackage>org.geonetwork.workshop2.model</modelPackage>
                <!--                <generateGenericResponseEntity>true</generateGenericResponseEntity>-->
                <!--                <useResponseEntity>false</useResponseEntity>-->

              </configOptions>
              <additionalProperties>
                <!--                <generateGenericResponseEntity>true</generateGenericResponseEntity>-->
                <!--                <useResponseEntity>false</useResponseEntity>-->

              </additionalProperties>
            </configuration>
          </execution>
        </executions>
      </plugin>
Steps to reproduce
Related issues/PRs

I tried doing a search, but every issue has the word "example" in it...

Suggest a fix

see description

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

Reproduce the issue with the attached OpenAPI schema using the spring generator and inspect the generated annotation in JavaSpring/pojo.mustache around the referenced line. Trace how array and additionalProperties examples become annotation strings, then verify the generated annotations and returned OpenAPI document use valid JSON-style array and map examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, spring
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.