AEP-0135 Linter Rules

Rules for AEP-135- Delete method

# Rules for AEP-135: Delete method

aep-135-http-body

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

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

Details

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

Examples

Incorrect code for this rule:

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

Correct code for this rule:

paths:
  '/books/{id}':
    delete:
      summary: Delete book
      responses:

Disabling

Important: HTTP DELETE 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-135-operation-id

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

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

Details

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

Examples

Incorrect code for this rule:

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

Correct code for this rule:

paths:
  '/books/{id}':
    delete:
      summary: Delete a book
      operationId: DeleteBook

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}/delete/operationId'
    rules:
      aep-135-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-135-response-204

Rule: A delete operation should have a 204 response.

This rule enforces that all Delete operations return a “204” (No Content) response.

Details

This rule looks for “delete” operations and complains if “responses” does not have a “204” property.

Examples

Incorrect code for this rule:

paths:
  '/books/{id}':
    delete:
      summary: Delete book
      responses:
        '200':
          description: Ok
        '4xx':
          description: Client error

Correct code for this rule:

paths:
  '/books/{id}':
    delete:
      summary: Delete book
      responses:
        '204':
          description: Book was deleted
        '4xx':
          description: Client error

Disabling

Use the “overrides” field of the ruleset file to override a specific instance. Include a comment explaining why the pattern could not be followed.