# parameter-naming

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

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.

```yaml
commands:
  lint:
    swagger:
      rules:
        parameter-naming:
          - warning
          - default: snake
            query: camel
            header: header
```

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

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