swagger-api / swagger-api/swagger-codegen
[JAVA] [jaxrs-jersey] Multiline description strings in the definition of requestBodies leads to invalid @ApiParam Java annotations
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Description
Having a multiline string in the definition of a request body leads to a multiline @ApiParam annotation in the generated file which results in compile errors
Swagger-codegen version
3.0.0-rc1
Swagger declaration file content or url
https://berlingroup.stackstorage.com/s/d4KSrRW9bDYmrSg
line 8691 defines the request body "paymentInitiation" with a multiline description:
paymentInitiation:
description: |
JSON request body for a payment inition request message
There are the following payment-products supported:
* "sepa-credit-transfers" with JSON-Body
* "instant-sepa-credit-transfers" with JSON-Body
* "target-2-payments" with JSON-Body
* "cross-border-credit-transfers" with JSON-Body
* "pain.001-sepa-credit-transfers" with XML pain.001.001.03 body for SCT scheme
* "pain.001-instant-sepa-credit-transfers" with XML pain.001.001.03 body for SCT INST scheme
* "pain.001-target-2-payments" with pain.001 body.
Only country specific schemes are currently available
* "pain.001-cross-border-credit-transfers" with pain.001 body.
Only country specific schemes are currently available
There are the following payment-services supported:
* "payments"
* "periodic-payments"
* "bulk-paments"
All optional, conditional and predefined but not yet used fields are defined.
required: true
Command line used for generation
java -jar swagger-codegen-cli-3.0.0-rc1.jar generate -l jaxrs-jersey -i psd2-api\ 1.2\ Update\ 2018-08-17.yaml --api-package test --model-package test --library jersey2
Steps to reproduce
Have a look at the generated file src/gen/java/test/V1Api.java. Line 1231 shows the invalid @ApiParam:
public Response initiatePayment(@ApiParam(value = "JSON request body for a payment inition request message
There are the following payment-products supported:
* "sepa-credit-transfers" with JSON-Body
* "instant-sepa-credit-transfers" with JSON-Body
....
Suggest a fix/enhancement
Multiline descriptions work for parameters. See e.g. line 8168 in the yaml file, where a parameter "paymentService" is defined:
paymentService:
name: payment-service
in: path
description: |
Payment service:
Possible values are:
* payments
* bulk-payments
* periodic-payments
required: true
This leads to a totally valid single line @ApiParam definition, see e.g. Line 121 in the generated file V1Api.java.
Please handle multine descriptions for requestBodies exactly as in parameters.
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 the generated src/gen/java/test/V1Api.java and compare the invalid requestBody @ApiParam near line 1231 with the valid parameter annotation near line 121. Trace the jaxrs-jersey generation path for requestBodies and parameter descriptions. Done means multiline requestBody descriptions produce a single valid Java annotation, with generation output compiling successfully.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, openapi
- Domain
- backend-api-design, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100