AEP-0158 Linter Rules

Rules for AEP-158: Pagination

aep-158-max-page-size-parameter

Rule: Operations that return collections should define an integer max_page_size parameter.

This rule enforces that all operations that return a collection define an integer max_page_size parameter.

Details

This rule looks at the parameters for an operation that returns a collection and complains if either the max_page_size parameter is missing or if it is not type: integer.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      description: 'No parameters'
  '/test2':
    get:
      description: 'No max_page_size parameter'
      parameters: []
  '/test3':
    get:
      description: 'max_page_size parameter is not an integer'
      parameters:
        - name: 'max_page_size'
          in: 'query'
          schema:
            type: 'string'

Correct code for this rule:

paths:
  '/test1':
    get:
      parameters:
        - name: 'max_page_size'
          in: 'query'
          schema:
            type: 'integer'

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/get'
    rules:
      aep-158-max-page-size-parameter: '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-158-page-token-parameter

Rule: Operations that return collections should define an string page_token parameter.

This rule enforces that all operations that return a collection define a string page_token parameter.

Details

This rule looks at the parameters for an operation that returns a collection and complains if either the page_token parameter is missing or if it is not type: string.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      description: 'No parameters'
  '/test2':
    get:
      description: 'No page_token parameter'
      parameters: []
  '/test3':
    get:
      description: 'page_token parameter is not a string'
      parameters:
        - name: 'page_token'
          in: 'query'
          schema:
            type: 'integer'

Correct code for this rule:

paths:
  '/test1':
    get:
      parameters:
        - name: 'page_token'
          in: 'query'
          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#/books/get'
    rules:
      aep-158-page-token-parameter: '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-158-page-token-parameter-optional

Rule: The page_token parameter must not be required.

This rule enforces that all operations that return a collection and define a page_token parameter do not define it as required.

Details

This rule looks at the parameters for an operation that returns a collection and complains if there is a page_token parameter with required: true.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      description: 'page_token parameter is required'
      parameters:
        - name: 'page_token'
          in: 'query'
          required: true
          schema:
            type: 'string'

Correct code for this rule:

paths:
  '/test1':
    get:
      parameters:
        - name: 'page_token'
          in: 'query'
          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#/books/get'
    rules:
      aep-158-page-token-parameter-optional: '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-158-response-array-property

Rule: Operations that return collections should define an integer max_page_size parameter.

This rule enforces that all operations that return a collection define an integer max_page_size parameter.

Details

This rule looks at the parameters for an operation that returns a collection and complains if either the max_page_size parameter is missing or if it is not type: integer.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      description: 'response does not have an array property'
      responses:
        200:
          content:
            'application/json':
              schema:
                type: 'object'
                properties:
                  results:
                    type: string
                  next_page_token:
                    type: string

Correct code for this rule:

paths:
  '/books':
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                type: 'object'
                properties:
                  results:
                    type: array
                    items:
                      '$ref': '#/components/schemas/book'
                  next_page_token:
                    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#/books/get'
    rules:
      aep-158-response-array-property: '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-158-response-next-page-token-property

Rule: Operations that return collections should define an integer max_page_size parameter.

This rule enforces that all operations that return a collection define an integer max_page_size parameter.

Details

This rule looks at the parameters for an operation that returns a collection and complains if either the max_page_size parameter is missing or if it is not type: integer.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      description: 'response does not have an next_page_token property'
      responses:
        200:
          content:
            'application/json':
              schema:
                type: 'object'
                properties:
                  results:
                    type: string

Correct code for this rule:

paths:
  '/books':
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                type: 'object'
                properties:
                  results:
                    type: array
                    items:
                      '$ref': '#/components/schemas/book'
                  next_page_token:
                    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#/books/get'
    rules:
      aep-158-response-next-page-token-property: '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-158-skip-parameter

Rule: Operations that return collections may define an integer skip parameter.

This rule enforces that all operations that return a collection and define a skip parameter define it as type: integer.

Details

This rule looks at the parameters for an operation that returns a collection and complains if a skip parameter is present but is not type: integer.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      description: 'skip parameter is not an integer'
      parameters:
        - name: 'skip'
          in: 'query'
          schema:
            type: 'string'

Correct code for this rule:

paths:
  '/test1':
    get:
      parameters:
        - name: 'skip'
          in: 'query'
          schema:
            type: 'integer'

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/get'
    rules:
      aep-158-skip-parameter: '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.