AEP-0132 Linter Rules

Rules for AEP-132- List method

# Rules for AEP-132: List method

aep-132-http-body

Rule: A list operation must not accept a request body.

This rule enforces that all List operations omit the HTTP body, as mandated in AEP-132.

Details

This rule looks for “get” operations on a path that does not end in a path parameter, and complains if the ‘requestBody’ field is present.

Examples

Incorrect code for this rule:

paths:
  '/books':
    get:
      summary: List books
      requestBody:
        content:
          'application/json':
            schema:
              type: string
      responses:

Correct code for this rule:

paths:
  '/books':
    get:
      summary: List books
      responses:

Disabling

Important: HTTP GET requests are unable to have an HTTP body, due to the nature of the protocol. The only valid way to include a body is to also use a different HTTP method (as depicted above).

aep-132-operation-id

Rule: The operation ID should be List{resource-plural}

This rule enforces that all standard List methods have an operationId field with a value that begins with “List”.

Details

This rule looks for “get” operations on a path that does not end in a path parameter, and complains if the ‘operationId’ field is not present or if the value does not begin with “list” (case insensitive) or a ”:” (for custom methods).

Examples

Incorrect code for this rule:

paths:
  # Missing operationId
  '/books':
    get:
      summary: list books
      responses:
  # operationId present but does not start with "list"
  '/publishers':
    get:
      summary: List publishers
      operationId: GetAllPublishers

Correct code for this rule:

paths:
  '/books':
    get:
      summary: List books
      operationId: listBooks

Disabling

If you need to violate this rule for a specific operation, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/books/get/operationId'
    rules:
      aep-132-operation-id: 'off'

If you need to violate this rule for an entire file, add an “override” to the Spectral rule file for the specific file without a fragment.

aep-132-param-types

Rule: List operation must use the correct type for any optional parameters.

This rule enforces that all List standard methods use the correct type for any optional parameters described in AEP-132.

Details

This rule looks at the query parameters of “get” operations on a path that does not end in a path parameter, and complains if it finds

• a parameter named filter that is not type: string
• a parameter named order_by that is not type: string
• a parameter named show_deleted that is not type: boolean

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      parameters:
        - name: filter
          in: query
          schema:
            type: object

Correct code for this rule:

paths:
  '/test1':
    get:
      parameters:
        - name: filter
          in: query
          schema:
            type: string

Disabling

If you need to violate this rule for a specific operation, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/paths/test1/get/parameters/0'
    rules:
      aep-132-param-types: 'off'

If you need to violate this rule for an entire file, add an “override” to the Spectral rule file for the specific file without a fragment.

aep-132-required-params

Rule: List operation should have no required parameters (except path parameters)

This rule enforces that all List standard methods do not have unexpected required parameters, as mandated in AEP-132.

Details

This rule looks at the parameters of “get” operations on a path that does not end in a path parameter, and complains if it finds any required parameters that are not path parameters (which must be required).

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      parameters:
        - name: force
          in: query
          required: true
          schema:
            type: boolean

Correct code for this rule:

paths:
  '/test1/{id}/test2':
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: force
          in: query
          schema:
            type: boolean

Disabling

If you need to violate this rule for a specific operation, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/paths/test1/get/parameters/0'
    rules:
      aep-132-required-params: 'off'

If you need to violate this rule for an entire file, add an “override” to the Spectral rule file for the specific file without a fragment.