AEP-0137 Linter Rules

Rules for AEP-137- Standard Apply method

# Rules for AEP-137: Standard Apply method

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

aep-137-operation-id

Rule: The operationId should be Apply{resource-singular}.

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

Details

This rule checks all Apply methods and complains if the operationId field is not present or if the value does not begin with “Apply” (case insensitive).

Examples

Incorrect code for this rule:

paths:
  '/test1/{id}':
    put:
      operationId: 'updateTest1'
      description: 'Incorrect operationId'
      requestBody:
        content:
          'application/json':
            schema:
              type: object
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/test1/{id}':
    put:
      operationId: 'applyTest1'
      description: 'Correct operationId'
      requestBody:
        content:
          'application/json':
            schema:
              type: object
      responses:
        200:
          description: Ok

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/{id}/put'
    rules:
      aep-137-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-137-request-body

Rule: The request body schema must be the resource itself.

This rule checks that all Apply methods accepts the resource to be replaced in the body of the request, as mandated in AEP-137.

Details

This rule checks all Apply methods and complains if there is no requestBody defined, or if the requestBody does not define a content with a schema that is an AEP resource.

Examples

Incorrect code for this rule:

paths:
  '/test1/{id}':
    put:
      description: 'No request body defined'
      responses:
        200:
          description: Ok
  '/test2/{id}'
    put:
      description: 'Request body is not an aep resource'
      requestBody:
        content:
          'application/json':
            schema:
              type: string
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/books/{id}':
    put:
      description: 'Request body is an aep resource'
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              'x-aep-resource':
                singular: book
                plural: books
      responses:
        200:
          description: Ok

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}/put'
    rules:
      aep-137-request-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-137-required-params

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

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

Details

This rule looks at all Apply 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}':
    put:
      description: 'Required query parameter'
      parameters:
        - name: force
          in: query
          required: true
          schema:
            type: boolean

Correct code for this rule:

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

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}/put'
    rules:
      aep-137-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-137-response-body

Rule: The response schema must be the resource itself.

This rule checks that Apply methods return the resource in the body of the response, as mandated in AEP-137.

Details

This rule looks at all Apply methods and complains if there is no responses field, no 200 response, or if the 200 response does not define a content with a schema that is an AEP resource.

Examples

Incorrect code for this rule:

paths:
  '/test1/{id}':
    put:
      description: 'No request body'
  '/test2/{id}':
    put:
      description: 'Request body is not a resource'
      requestBody:
        content:
          application/json:
            schema:
              type: string
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/books/{id}':
    put:
      operationId: ApplyBook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              'x-aep-resource':
                singular: book
                plural: books

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/post/parameters/0'
    rules:
      aep-137-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-137-unknown-optional-params

Rule: Apply methods should have no unknown optional parameters

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

Details

This rule looks at the parameters all Apply methods, and complains if it finds any optional query parameters that are described in the AEPs. Currently there are no allowed optional query parameters for an Apply method.

Examples

Incorrect code for this rule:

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

Correct code for this rule:

paths:
  '/publishers/{publisherId}/books/{id}':
    put:
      description: No unknown optional params
      parameters:
        - name: publisherId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          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/books/put/{id}/parameters/0'
    rules:
      aep-137-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.