swagger-api / swagger-api/swagger-codegen
Meta issue: parameter name mangling breaks client or server functionality
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Description
In many languages, parameter names are mangled to conform to the conventions of the language, not be reserved words, etc. For Java, this is conversion to camelCase.
In several languages, the generated code only actually works with the protocol described in the API definition when the parameter mangling results in the same name as the original, otherwise different parameter names are actually sent to the server (for clients) or accepted from the client (for servers).
This is a meta issue collecting my research I have done.
Swagger-codegen version
I worked on master of 2017-02-27, i.e. shortly before the release of 2.2.2.
spring
I first found this for spring-mvc (later renamed to just spring) in #1219, for path and header parameters. It was fixed for header parameters some time ago, is still wrong for path, query and form parameters.
Some days ago it was also noted by @techlogix in #4870.
I filed PR #4875 fixing this for the spring-based languages.
html2
Issue #4864 is mentioning the problem, it was seemingly resolved in #4602.
Potentially affected languages
I did a search for {{paramName}} in the templates, especially looking for where it is used in a string which then is used for sending/accepting the parameter to the server/from the client. In those cases most probably {{baseName}} should be used instead.
I made a preliminary commit with all the changes I found (and later a second one with files I missed).
I'll go through the changes here, list the languages up there with details and create a pull request with just the changes for one language (and the regenerated samples). Someone with knowledge of the specific language should check them and confirm that that was really a bug and the new version is better.
Here is an overview of my findings in general (❌ = potentially broken). There might be some languages which don't have any parameter transformation, then {{baseName}} would be always the same as {{paramName}}.
| Language (template directory name) | Pull request | path | query | form | header | Other comments |
|---|---|---|---|---|---|---|
| Groovy | #5030 | ❌ | ❌ | It looks like path, form and body parameters are not supported at all. | ||
| JavaJaxRS | #4918 | ❌ * | It looks like only file-typed form parameters (i.e. file uploads) are affected. | |||
| JavaJaxRs/cxf | #4918 | ❌ | here all kinds of form parameters. | |||
| JavaJaxRs/cxf-di | #4918 | ❌ | ||||
| JavaJaxRs/resteasy | #4918 | ❌ | ||||
| JavaJaxRs/spec | #4918 | ❌ | ||||
| JavaJaxRs/libraries/jersey1 | #4918 | ❌ | Only with vendor extension x-multipart. And for file parameters the name will always be file??? |
|||
| JavaJaxRs/resteasy/eap | #4918 | ❌ | ||||
| JavaSpring | #4875 (merged) | ❌ | ❌ | ❌ | First noted in #1219, later in #4460. | |
| JavaSpring/libraries/spring-cloud | #4919 | ❌ | (file uploads have name "file"?) | |||
| MSF4J | #4917 | ❌ * | For non-file parameters those which have a x-multipart vendor extension are affected, also all file-parameters (uploads). |
|||
| cpprest | # | Not totally sure ... it is in the section for multipart/form-data, but about the body parameter? That one doesn't have any on-the-wire name, I think. | ||||
| dart | #5019 | ❌ | ||||
| elixir | #5021 | ❌ | ❌ | ❌ | ||
| flash | #5022 | ❌ | ❌ | ❌ | ||
| flaskConnexion | # | ❓ | ❓ | ❓ | ❓ | I didn't figure out where the parameter names are mapped. Updated only in the doc comment. |
| go | #4440 | ❌ | ||||
| htmlDocs2 | #5173 | ❌* | Seems to just affect the query parameters in the example curl command. | |||
| lumen | # | ❓ | ❌ | ❌ | ❌ | The code for the non-path parameters is affected. I'm not sure how path parameter translation works at all. |
| nancyfx | # | ❌ | ❌ | ❌ | ❌ | To be checked. |
| objc | # | ❌ * | Just file upload form parameters seem to be affected. | |||
| scalatra | # | ❌ | ❌ | ❌ | ❌ | Basically the same code is also used for body parameters, which don't have any name on the wire. |
| silex | #4817 | ❓ | ❌ | ❌ | ❓ | I didn't figure out how path parameter name translation works here. Header parameters seem to not be used at all? |
| sinatra | # | ❌ | ❌ | ❓ | ❌ | This is just some structure collecting meta info about the parameters (i.e. basically the swagger definitions). Not sure how the actual parameters are mapped. |
| slim | # | ❓ | ❌ | ❌ | ❓ | Not sure if and how path params are handled. Header parameters seem to be not mapped at all? |
| swift3 | #4916 | ❌ | ||||
| tizen | # | ❌ | ❌ | |||
| ze-ph | # | This seems to get the body parameter from the request by its name? |
For the following languages I couldn't figure out what was going on:
- finch
- flaskConnexion
- JavaInflector
- JMeter
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
Search the generator templates for {{paramName}} and compare uses in wire-level path, query, form, and header handling with {{baseName}}. Review the language-specific template directories and the referenced pull requests, then regenerate the affected samples. Done means each affected generator preserves the API definition's original parameter names while retaining valid local names.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, csharp, dart, elixir, go, groovy, java, objective-c, php, python, ruby, scala, swift
- Domain
- api, backend-api-design, tooling
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 15/100