swagger-api / swagger-api/swagger-codegen

[JavaScript] CodeGen for Docs Camelizes Variables Without My Consent

Open
#6,530 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Client: JavaScript/Node.js help wanted Issue: Bug
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
  1. Generate code via command line
  2. 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.