springmvc: parameter names don't survive generation

[ePaul]

Summary
When parameter names are sanitized, the HTTP side parameters can not be matched again with the Java side parameters.

Details
When generating springmvc or jaxrs Java server classes, each swagger parameter becomes an annotated parameter of the method, with both Swagger and Spring/JaxRS annotations.

Some of these annotations' arguments are meant to transport the parameter name as used in the protocol, but they are currently either empty (falling back to some default) or filled with the sanitized Java parameter name – which is wrong.

Reproducible

Here is my bug-trigger.yaml:

swagger: '2.0'
info:
  title: Swagger Codegen bug trigger
  description: |
     This demonstrates a bug in swagger-codegen.
  version: 0.0.1
basePath: /api
definitions:
  example:
    type: object
    properties:
      foo:
        type: object
        properties:
          bar:
            type: string
paths:
  "/path/{foo_id}":
    parameters:
      - name: foo_id
        in: path
        type: string
    get:
      parameters:
       - name: If-None-Match
         in: header
         type: string
      responses:
        200:
          description: "blub"
          schema:
            $ref: "#/definitions/example"

(The important part is the Path here.)

When using the spring-mvc language, it generates the following file (beside others):

[imports snipped]

@Controller
@RequestMapping(value = "/path", produces = {APPLICATION_JSON_VALUE})
@Api(value = "/path", description = "the path API")
@javax.annotation.Generated(value = "class io.swagger.codegen.languages.SpringMVCServerCodegen", date = "2015-09-11T17:10:19.015+02:00")
public class PathApi {


  @ApiOperation(value = "", notes = "", response = Example.class)
  @ApiResponses(value = { 
    @ApiResponse(code = 200, message = "blub") })
  @RequestMapping(value = "/{foo_id}", 


    method = RequestMethod.GET)
  public ResponseEntity<Example> pathFooIdGet(
@ApiParam(value = "",required=true ) @PathVariable("fooId") String fooId
,

@ApiParam(value = ""  ) @RequestHeader(value="ifNoneMatch", required=false) String ifNoneMatch
)
      throws NotFoundException {
      // do some magic!
      return new ResponseEntity<Example>(HttpStatus.OK);
  }


}

The parameters If-None-Match and foo_id got transformed to ifNoneMatch and fooId, with no trace of the original names. The @RequestHeader and @PathVariable names even have the sanitized names instead of the original one.

I'm not sure about Swagger's @ApiParam annotations – I guess those should have the correct names, too.

When using the jaxrs "language", it generates this:

[imports snipped]

@Path("/path")


@io.swagger.annotations.Api(value = "/path", description = "the path API")
@javax.annotation.Generated(value = "class io.swagger.codegen.languages.JaxRSServerCodegen", date = "2015-09-11T17:16:59.995+02:00")
public class PathApi  {

   private final PathApiService delegate = PathApiServiceFactory.getPathApi();

    @GET
    @Path("/{foo_id}")


    @io.swagger.annotations.ApiOperation(value = "", notes = "", response = Example.class)
    @io.swagger.annotations.ApiResponses(value = { 
        @io.swagger.annotations.ApiResponse(code = 200, message = "blub", response = Example.class) })

    public Response pathFooIdGet(@ApiParam(value = "",required=true ) @PathParam("foo_id") String fooId,
    @ApiParam(value = ""  )@HeaderParam("If-None-Match") String ifNoneMatch)
    throws NotFoundException {
        return delegate.pathFooIdGet(fooId,ifNoneMatch);
    }
}

Here the JaxRS annotations have the correct values, the swagger annotations still have none.

I guess similar things might happen in other language generators.

Analysis
I guess the *param.mustache files need to be changed to use baseName instead of paramName at the correct places, and to have the names additionally in the @ApiParam annotation (if this is thought sensible).

[wing328]

@ePaul thanks for the detailed analysis. I agree with you that baseName (the original parameter name or the name of the JSON key) should be used instead of paramName, which is sanitised to make sure it won't caused compilation error.

cc @dilipkrish, who is the expert in SpringMVC

[dilipkrish]

@ePaul 👍 Not super familiar with codegen, just enough to be dangerous :-o It seems like a reasonable change to me. Did you verify that the api docs that are round-triped work as you expected? /c @wing328

[ePaul]

@dilipkrish No, I didn't yet get this to work due to other problems.

[wing328]

@ePaul when you've time, can you please pull the latest to see if it's still an issue?

[ePaul]

I just tried with 2.2.1. First surprise: Language spring-mvc doesn't exist anymore.
With language spring (and the same file), I get this:

@Api(value = "path", description = "the path API")
public interface PathApi {

    @ApiOperation(value = "", notes = "", response = ExampleDTO.class, tags={  })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "blub", response = ExampleDTO.class) })
    @RequestMapping(value = "/path/{foo_id}",
        method = RequestMethod.GET)
    ResponseEntity<ExampleDTO> pathFooIdGet(
@ApiParam(value = "",required=true ) @PathVariable("fooId") String fooId


,
@ApiParam(value = ""  ) @RequestHeader(value="If-None-Match", required=false) String ifNoneMatch

The @RequestHeader looks nice, but I think the @PathVariable is still wrong. (And there also seem to be a bunch of superfluous line breaks.) I didn't try to run a server based on this, though.

Same effect with current master (d2d5553).

[wing328]

@ePaul thanks for checking.

We did flag the spring PR as a breaking change in 2.2.0: #3133 (comment). Please refer to the upgrade note for a smooth upgrade.

I also notice about the line break formatting issue and will try to fix it later with a PR.

For @PathVariable, what would be the correct value looks like for the above example?