# parameter-naming

Source: https://apigenie.pl/docs/linter/swagger/rules/parameter-naming

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. 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](/docs/linter/openapi/rules/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.

```yaml
commands:
  lint:
    swagger:
      rules:
        parameter-naming:
          - warning
          - default: snake_case
            query: camelCase
            header: Header-Case
```

## Examples

**Good**. Parameters follow the default conventions.

```yaml
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`.

```yaml
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.
```
