AEP-0131 Linter Rules

Rules for AEP-131- Standard Get method

# Rules for AEP-131: Standard Get method

The aep-131 rules check the descriptions of standard Get methods, which are “get” operations on path that ends in a path parameter with no appended action (indicating a custom method).

aep-131-operation-id

Rule: The operation ID should be Get{resource-singular}

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

Details

This rule looks for “get” 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 “Get” (case insensitive) or a ”:” (for custom get methods).

Examples

Incorrect code for this rule:

paths:
  # Missing operationId
  '/books/{id}':
    get:
      summary: Get book
      responses:
  # operationId present but does not start with "get"
  '/publishers/{id}':
    get:
      summary: Get a publisher
      operationId: FetchPublisher

Correct code for this rule:

paths:
  '/books/{id}':
    get:
      summary: Get book
      operationId: GetBook

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}/get/operationId'
    rules:
      aep-131-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-131-request-body

Rule A get method must not accept a request body.

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

Details

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

Examples

Incorrect code for this rule:

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

Correct code for this rule:

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

aep-131-required-params

Rule: Get methods must have no required parameters other than path parameters

This rule checks that Get methods have no required parameters other than path parameters, as mandated in AEP-131.

Details

This rule looks at all Get methods 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/{id}':
    get:
      description: 'Required query parameter'
      parameters:
        - name: force
          in: query
          required: true
          schema:
            type: boolean

Correct code for this rule:

paths:
  '/books/{id}':
    get:
      description: 'Only path params are required'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: force
          in: query
          schema:
            type: boolean
      responses:
        200:
          description: Ok
          content:
            'application/json':
              schema:
                type: object

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/books/{id}/get'
    rules:
      aep-131-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.

aep-131-response-body

Rule: The response should include the AEP resource.

This rule enforces that all standard Get operations have an response body that represents a resource.

Details

This rule looks for “get” operations on a path that ends in a path parameter, and complains if the schema of the 200 response contains the x-aep-resource specification extension.

Examples

Incorrect code for this rule:

paths:
  '/books/{id}':
    get:
      summary: Get book
      responses:
        '200':
          description: A Book
          content:
            'application/json':
              # Missing x-aep-resource extension
              schema:
                type: object

Correct code for this rule:

paths:
  '/books/{id}':
    get:
      summary: Get book
      responses:
        '200':
          description: A Book
          content:
            'application/json':
              # Missing x-aep-resource extension
              schema:
                type: object
                'x-aep-extension':
                  singular: book

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}/get/responses/200/content/application/json/schema'
    rules:
      aep-131-response-body: '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-131-unknown-optional-params

Rule: Get methods should have no unknown optional parameters

This rule checks that Get methods have no optional parameters other than parameters defined in AEP-131 or other AEPs.

Details

This rule looks at the parameters all Get methods, and complains if it finds any optional query parameters that are not described in the AEPs. Optional parameters allowed on Get methods defined in other AEPs include:

• read_mask - defined in AEP-157
• view - defined in AEP-157

Examples

Incorrect code for this rule:

paths:
  '/test1/{id}':
    get:
      description: Unknown force optional parameter
      parameters:
        - name: force
          in: query
          schema:
            type: boolean

Correct code for this rule:

paths:
  '/publishers/{publisherId}/books/{id}':
    get:
      description: No unknown optional params
      parameters:
        - name: publisherId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: view
          in: query
          schema:
            enum: ['BASIC', 'FULL']

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/books/get/{id}/parameters/0'
    rules:
      aep-131-unknown-optional-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.