parameter-naming

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at warning, All at error

This rule checks whether parameter names of a Swagger 2.0 document follow a naming convention.

Rule details

Consistent parameter names make an API easier to learn and use. Different parameter locations usually follow different conventions: HTTP headers are traditionally written in Header-Case, while query parameters often use kebab-case or snake_case.

The parameter-naming rule checks parameters of operations, of path items and the shared parameters under the root parameters, converts each name to the convention configured for its location (path, query, header or formData) and reports Parameter should be named <converted name> when the converted name differs from the actual one.

Body parameters are skipped, since their names do not appear in requests. Parameter references ($ref) are skipped; the referenced shared parameter is checked where it is defined.

Without options, query parameters must use kebab-case, header parameters Header-Case and path and form data parameters snake_case.

The OpenAPI linter has a rule of the same name, parameter-naming, for OpenAPI 3.x documents.

Turn the rule off when parameter names are dictated by an existing implementation that cannot be changed.

Configuration

Supported conventions are camelCase, camelCaseStrict, CONST_CASE (also UPPER_CASE and SCREAMING_SNAKE_CASE), PascalCase, PascalCaseStrict, snake_case, kebab-case and Header-Case (the strict forms reject two capitals in a row, e.g. userID).

The options are either a string or an object:

  • a string sets the convention for parameters in every location, including query and header parameters;
  • an object must have a default property with the convention for every location, and may override it for individual locations with the path, query, header and formData properties. Locations that are not listed use the default convention.
commands:
  lint:
    swagger:
      rules:
        parameter-naming:
          - warning
          - default: snake_case
            query: camelCase
            header: Header-Case

Examples

Good. Parameters follow the default conventions.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets/{pet_id}:
    get:
      parameters:
        - name: pet_id
          in: path
          required: true
          type: string
        - name: page-size
          in: query
          type: integer
        - name: X-Request-Id
          in: header
          type: string
      responses:
        '200':
          description: A single pet.

Bad. With the default conventions, pageSize should be named page-size, x-request-id should be named X-Request-Id and firstName should be named first_name.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    post:
      consumes: [application/x-www-form-urlencoded]
      parameters:
        - name: pageSize
          in: query
          type: integer
        - name: x-request-id
          in: header
          type: string
        - name: firstName
          in: formData
          type: string
      responses:
        '201':
          description: The pet was added.

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        parameter-naming: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?