AEP-0134 Linter Rules

Rules for AEP-134: Standard Update method

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

aep-134-content-type

Rule: The method must support MIME type “application/merge-patch+json”

This rule ensures that all Update methods define a request body with content-type of “application/merge-patch+json”.

Details

This rule checks all Update methods and complains if the method does not define a requestBody, the requestBody does not contain a content field, or if the content field does not contain an entry for the “application/merge-patch+json” MIME type.

Examples

Incorrect code for this rule:

paths:
  '/test1/{id}':
    patch:
      description: 'No request body'
  '/test2/{id}':
    patch:
      description: 'Request body is not merge-patch+json'
      requestBody:
        content:
          'application/json':
            schema:
              type: object
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
'/test1/{id}':
  patch:
    description: 'Request body is merge-patch+json'
    requestBody:
      content:
        'application/merge-patch+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}/patch'
    rules:
      aep-134-content-type: '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-134-operation-id

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

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

Details

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

Examples

Incorrect code for this rule:

paths:
  '/test1/{id}':
    patch:
      operationId: 'modifyTest1'
      description: 'Incorrect operationId'
      requestBody:
        content:
          'application/merge-patch+json':
            schema:
              type: object
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/test1/{id}':
    patch:
      operationId: 'updateTest1'
      description: 'Correct operationId'
      requestBody:
        content:
          'application/merge-patch+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}/patch'
    rules:
      aep-134-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-134-request-body

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

This rule checks that all Update methods accepts the resource to be updated in the body of the request, as mandated in AEP-134.

Details

This rule checks all Update 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}':
    patch:
      description: 'No request body defined'
      responses:
        200:
          description: Ok
  '/test2/{id}'
    patch:
      description: 'Request body is not an aep resource'
      requestBody:
        content:
          'application/merge-patch+json':
            schema:
              type: string
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/books/{id}':
    patch:
      description: 'Request body is an aep resource'
      requestBody:
        content:
          'application/merge-patch+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}/patch'
    rules:
      aep-134-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-134-required-params

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

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

Details

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

Correct code for this rule:

paths:
  '/books/{id}':
    patch:
      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/merge-patch+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}/patch'
    rules:
      aep-134-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-134-response-body

Rule: The response schema must be the resource itself.

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

Details

This rule looks at all Update 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}':
    patch:
      description: 'No request body'
  '/test2/{id}':
    patch:
      description: 'Request body is not a resource'
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              type: string
      responses:
        200:
          description: Ok

Correct code for this rule:

paths:
  '/books/{id}':
    patch:
      operationId: UpdateBook
      requestBody:
        content:
          application/merge-patch+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-134-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-134-unknown-optional-params

Rule: Update methods should have no unknown optional parameters

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

Details

This rule looks at the parameters all Update 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 Update method.

Examples

Incorrect code for this rule:

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

Correct code for this rule:

paths:
  '/publishers/{publisherId}/books/{id}':
    patch:
      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/patch/{id}/parameters/0'
    rules:
      aep-134-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.