parameter-naming

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

This rule checks that parameter names follow one naming convention per location: kebab-case for query parameters, Header-Case for header parameters and snake_case for the others, unless configured otherwise.

Rule details

A client author who has seen one parameter should be able to spell the next: page-size and pageSize in the same API cost a lookup each time. The conventions the rule knows:

  • CONST_CASE (also UPPER_CASE and SCREAMING_SNAKE_CASE): THIS_IS_CONST_CASE
  • camelCase: thisIsCamelCase, acronyms allowed (userID)
  • camelCaseStrict: thisIsCamelCase, no two capitals in a row (userId)
  • kebab-case: this-is-kebab-case
  • PascalCase: ThisIsPascalCase, acronyms allowed (HTTPServer)
  • PascalCaseStrict: ThisIsPascalCase, no two capitals in a row (HttpServer)
  • Header-Case: This-Is-Header-Case
  • snake_case: this_is_snake_case

The rule reports Parameter should be named ... with the name in the expected convention.

Configuration

A convention name, used for every location, or an object with a default convention and any of path, query, header and cookie overriding it.

Configuration example 1. The two are the same: PascalCase everywhere.

commands:
  lint:
    rules:
      parameter-naming:
        - warning
        - PascalCase
commands:
  lint:
    rules:
      parameter-naming:
        - warning
        - default: PascalCase

Configuration example 2. snake_case by default, kebab-case in the query string and Header-Case in headers.

commands:
  lint:
    rules:
      parameter-naming:
        - warning
        - default: snake_case
          query: kebab-case
          header: Header-Case

Examples

Good. With the default configuration.

paths:
  /users/{user_id}:
    get:
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
        - name: page-size
          in: query
          schema:
            type: integer
        - name: X-Request-Id
          in: header
          schema:
            type: string

Bad. A query parameter in camel case.

paths:
  /users:
    get:
      parameters:
        - name: pageSize
          in: query
          schema:
            type: integer

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.rules has the details.

commands:
  lint:
    rules:
      parameter-naming: off
Was this helpful?