swagger-api / swagger-api/swagger-codegen

[JAVA] [jaxrs-jersey] Multiline description strings in the definition of requestBodies leads to invalid @ApiParam Java annotations

Open
#8,664 2 comments 1 reaction 0 assignees View on GitHub

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.