Linter rulesSwagger 2.0parameter-naming

parameter-naming

Since 0.9.0

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, header parameters header and path and form data parameters snake.

Configuration

Supported conventions are camel, camel-strict, const, pascal, pascal-strict, snake, kebab and header (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
            query: camel
            header: header

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.

When Not to Use It

You may disable this rule when parameter names are dictated by an existing implementation that cannot be changed.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading