AEP-0136 Linter Rules

Rules for AEP-136: Custom Methods

aep-136-http-method

Rule: Custom methods should use POST or GET.

This rule enforces that all Custom operations use POST or GET methods.

Details

This rule looks for “custom” operations and complains if operation uses anything except POST or GET methods.

Examples

Incorrect code for this rule:

paths:
  '/books/{id}:archive':
    delete:
      summary: Archive book
      requestBody:
        content:
          'application/json':
            schema:
              type: string
      responses:

Correct code for this rule:

paths:
  '/books/{id}:archive':
    post:
      summary: Archive book
      responses:

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/{id}:archive/delete/operationId'
    rules:
      aep-136-http-method: 'off'

aep-136-operation-id

Rule: The operation ID should start with a colon and a capital letter

This rule enforces that all Custom methods start with a colon and a capital letter.

Details

This rule looks for “custom” operations on a path that ends in a path parameter, and complains if the ‘operationId’ field is not present or if the value does not begin with ”:” and a capital letter.

Examples

Incorrect code for this rule:

paths:
  # Missing operationId
  '/books/{id}:archive':
    delete:
      summary: Archive a book
      responses:
  # operationId present but does not start with ":"
  '/publishers/{id}:refresh':
    delete:
      summary: Refresh publisher
      operationId: RefreshPublisher

Correct code for this rule:

paths:
  '/books/{id}:archive':
    delete:
      summary: Archive a book
      operationId: :ArchiveBook

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/{id}:archive/delete/operationId'
    rules:
      aep-136-operation-id: 'off'

aep-136-get-idempotency

Rule GET-based custom methods must be idempotent and have no request body.

This rule enforces that all Custom Get operations omit the HTTP body, as mandated in AEP-136.

Details

This rule looks for Custom “get” operations and complains if the ‘requestBody’ field is present.

Examples

Incorrect code for this rule:

paths:
  '/books/{id}:archive':
    get:
      summary: Archive a book
      requestBody:
        content:
          'application/json':
            schema:
              type: string
      responses:

Correct code for this rule:

paths:
  '/books/{id}:archive':
    get:
      summary: Archive book
      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.