OpenAPITools / OpenAPITools/openapi-generator
[BUG] `example:` - List<String> and Map<String, XXX> doesn't create correct annotations (`spring`)
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
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
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
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
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