swagger-api / swagger-api/swagger-codegen
[JavaScript] CodeGen for Docs Camelizes Variables Without My Consent
Nobody has claimed this yet.
- Dominant language
- Mustache
- Stars
- 17.8k
- Forks
- 6k
- PR merge metrics
- No merged PRs in 30d
Description
Description
We just found that our JavaScript docs being created by Swagger are incorrect. Our API takes variables like "grant_type" in the POST body. However, the SDK docs tell the user to use "grantType". We see that the Javascript CodeGen camelizes all the variables for the documentation, which confuses the dev reading the documentation.
Here is a sample documentation page:
https://github.com/bluejeans/api-rest-onvideo/blob/master/libs/javascript/docs/GrantRequestClient.md
Swagger-codegen version
2.2.3. Looks to have always been this way.
Swagger declaration file content or url
GrantRequestClient:
type: object
properties:
grant_type:
type: string
default: client_credentials
description: The type of access token you are requesting.
client_id:
type: string
description: The value given within the BlueJeans Enterprise Administration console.
client_secret:
type: string
description: The value given within the BlueJeans Enterprise Administration console.
required:
- grant_type
- client_id
- client_secret
Command line used for generation
java -jar swagger-codegen-cli.jar generate -i ../swagger.yaml -l javascript -o ../libs/javascript --config config.javascript.json
Config just contains:
{
"moduleName":"X",
"projectName":"Y",
"projectDescription":"Z",
"projectLicenseName":"MIT",
"gitUserId":"A",
"gitRepoId":"B#npm-repo"
}
Steps to reproduce
- Generate code via command line
- View documentation file of a model that uses _ in a variable name
Related issues/PRs
Suggest a fix/enhancement
Can we stop camelizing variables in the docs that should not be modified?
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 JavaScript generation command and the sample GrantRequestClient.md linked in the issue, then trace how model property names are rendered in generated documentation. Reproduce the underscore-to-camelCase behavior with the provided Swagger YAML. Done means generated JavaScript documentation preserves names such as grant_type, client_id, and client_secret, with coverage for the regression.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100