OpenAPITools / OpenAPITools/openapi-generator
[BUG][jaxrs-spec] Encoding issue
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 (example)?
- 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
When generating classes from openapi.yaml custom specification with french special characters, Swagger @ApiOperation "value" fields contain badly encoded special characters.
This is a problem for me because my API documentation inside Swagger-UI is well exposed but unreadable...
Indeed, "Récupérer la liste des titi" becomes "Récupérer la liste des titi".
openapi-generator version
I am usign 5.1.0 version of openapi-generator-maven-plugin
OpenAPI declaration file content or url
openapi.yaml
# OpenAPI 3.0.3 specification documentation: https://spec.openapis.org/oas/v3.0.3
openapi: 3.0.3
info:
description: "API du toto"
version: "1.0"
title: Toto OpenAPI specification
paths:
/toto/titi:
get:
summary: Récupérer la liste des titi
operationId: findToto
parameters:
- name: page
in: query
description: Numéro de la page à afficher
schema:
type: integer
minimum: 0
default: 0
- name: size
in: query
description: Nombre d'éléments à afficher par page
schema:
type: integer
minimum: 1
maximum: 10
default: 10
- name: sort
in: query
description: Champs avec lequel trié le resultat
schema:
type: string
enum: [id, pacage, attribute, statut]
default: id
- name: order
in: query
description: Ordre de trie du resultat
schema:
type: string
enum: [asc, desc]
default: asc
responses:
200:
description: La liste des titi
content:
application/json:
schema:
type: array
items:
$ref: "definitions.yaml#/definitions/Toto"
post:
summary: Insérer un nouveau toto
operationId: insertToto
requestBody:
description: toto à insérer
required: true
content:
application/json:
schema:
$ref: 'definitions.yaml#/definitions/Toto'
responses:
201:
description: Le toto a été inséré
/toto/titi/{idToto}:
get:
summary: Obtenir les détails du toto
operationId: getToto
parameters:
- name: idToto
in: path
description: Identifiant du toto
required: true
schema:
type: integer
format: int64
responses:
200:
description: Le toto demandé
content:
application/json:
schema:
$ref: "definitions.yaml#/definitions/Toto"
put:
summary: Mettre à jour un toto existant ou en insérer un nouveau
operationId: updateToto
parameters:
- name: idToto
in: path
description: Identifiant du toto
required: true
schema:
format: int64
type: integer
requestBody:
description: toto à mettre à jour ou à insérer
required: true
content:
application/json:
schema:
$ref: "definitions.yaml#/definitions/Toto"
responses:
200:
description: toto a été mis à jour
201:
description: Le toto a été inséré
delete:
summary: Supprimer un toto existant
operationId: deleteToto
parameters:
- name: idToto
in: path
description: Identifiant du toto
required: true
schema:
format: int64
type: integer
responses:
200:
description: toto a été supprimé
definitions.yaml
# OpenAPI 3.0.3 specification documentation: https://spec.openapis.org/oas/v3.0.3
openapi: 3.0.3
definitions:
Tutu:
type: object
properties:
insee:
type: string
attribute:
type: string
Tata:
type: object
properties:
id:
type: integer
format: int64
pacage:
type: string
attribute:
type: string
statut:
type: string
tutu:
$ref: '#/definitions/Tutu'
dateHistorisation:
type: string
format: date-time
Toto:
type: object
properties:
id:
type: integer
format: int64
pacage:
type: string
attribute:
type: string
statut:
type: string
tutu:
$ref: '#/definitions/Tutu'
tataList:
type: array
items:
$ref: '#/definitions/Tata'
Generation Details
I am using the following maven configuration:
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>5.1.0</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<!-- openapi-generator-maven-plugin configuration documentation: https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin -->
<configuration>
<inputSpec>openapi.yaml</inputSpec>
<!-- https://openapi-generator.tech/docs/generators/#server-generators -->
<generatorName>jaxrs-spec</generatorName>
<modelNameSuffix>TO</modelNameSuffix>
<!-- configOptions documentation for jaxrs-spec generator: https://openapi-generator.tech/docs/generators/jaxrs-spec/ -->
<configOptions>
<sourceFolder>src/main/java</sourceFolder>
<interfaceOnly>true</interfaceOnly>
<returnResponse>true</returnResponse>
<serializableModel>true</serializableModel>
<generatePom>false</generatePom>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
Steps to reproduce
- run
mvn clean install - look generated classes inside
target/src/main/java/.../TotoApi.javato see@ApiOperation(value = "some badly encoded characters", notes = "", tags={ }) - look generated doc inside
target/src/main/openapi/openapi.yamlto seesummaryanddescriptiontags with badly encoded characters
Related issues/PRs
Suggest a fix
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 by running the Maven configuration against openapi.yaml and compare the French text in the generated target/src/main/java/.../TotoApi.java and target/src/main/openapi/openapi.yaml with the source. Check how the jaxrs-spec generator handles the encoding of summary and description values. Done means generated annotations and OpenAPI output preserve characters such as é correctly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, backend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100