http-status-code-ruleset.yaml

#
# Copyright 2019-2022 Groupe BPCE
#
# Licensed under the Apache License, Version 2.0 (the License);
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an AS IS BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

extends:
  - [spectral:oas, off] # needed to activate Spectral operation-2xx-response rule or to use the oasOp2xxResponse function
rules:
  # Adapted from existing Spectral OAS rule to change rule name and description (only severity can be overiddden using the following line)
  #operation-2xx-response: error
  # RuleSet functions are no more accessible
  # so can't use oasOpSuccessResponse
  # http-status-code-mandatory-2xx:
    # recommended: true
    # description: Operation must have at least one 2xx response.
    # message: "{{description}} ({{path}})"
    # severity: error
    # tags:
      # - http status code
    # given: "$.paths.*[?( @property === 'get' || @property === 'put' || @property === 'post' || @property === 'delete' || @property === 'options' || @property === 'head' || @property === 'patch' || @property === 'trace' )]"
    # then:
      # - field: responses
        # function: oasOpSuccessResponse

  # Instead of custom http-status-code-mandatory-2xx, we use default operation-success-response ruleset
  operation-success-response: error

  http-status-code-mandatory-401:
    recommended: true
    description: Operation must return a 401 error response
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: $.paths.*.*.responses
    then:
      - field: "401"
        function: truthy

  http-status-code-mandatory-500:
    recommended: true
    description: Operation must return a 500 error response
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: $.paths.*.*.responses
    then:
      - field: "500"
        function: truthy

  http-status-code-404-when-path-parameters:
    recommended: true
    description: On operation on a path with a path parameter must return a 404 HTTP status code
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: "$.paths[?(/{/i.test(@property))].*.responses"
    then:
      - field: "404"
        function: truthy

  http-status-code-no-404-when-no-path-parameters:
    recommended: true
    description: No 404 HTTP status code should be returned on operation on a path without path parameters
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: "$.paths[?(!/{/i.test(@property))].*.responses"
    then:
      - field: "404"
        function: falsy

  http-status-code-400-operation-level-query-body-header-param:
    recommended: true
    description: Operation must return a 400 HTTP status code in case of query, body or header parameters
    # {{error}} and not {{path}} because when using the ^ operator, the returned path is not the good one but OK in error
    message: '{{description}} ({{error}}) ({{path}})'
    severity: error
    tags:
      - http status code
    given:
      - $.paths.*.[?(@.requestBody)].responses
      - $.paths.*.*.parameters[?(/(query|body|header)/.test(@.in))]^^^.responses
    then:
      - field: "400"
        function: truthy

  # Using separate rule for each method to stay user friendly (get, put and patch could be handled with the same rule)
  http-status-code-get:
    recommended: true
    description: Get operation can only return 200, 400, 401, 403, 404, and 500 HTTP status codes
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: $.paths.*.get.responses
    then:
      - field: "@key"
        function: enumeration
        functionOptions:
          values:
            - '200'
            - '400'
            - '401'
            - '403'
            - '404'
            - '500'
            - '503'

  http-status-code-put:
    recommended: true
    description: Put operation can only return 200, 400, 401, 403, 404, and 500 HTTP status codes
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: $.paths.*.put.responses
    then:
      - field: "@key"
        function: enumeration
        functionOptions:
          values:
            - '200'
            - '400'
            - '401'
            - '403'
            - '404'
            - '500'
            - '503'

  http-status-code-patch:
    recommended: true
    description: Patch operation can only return 200, 204, 400, 401, 403, 404, and 500 HTTP status codes
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: $.paths.*.patch.responses
    then:
      - field: "@key"
        function: enumeration
        functionOptions:
          values:
            - '200'
            - '204'
            - '400'
            - '401'
            - '403'
            - '404'
            - '500'
            - '503'

  http-status-code-delete:
    recommended: true
    description: Delete operation can only return 200, 204, 400, 401, 403, 404, and 500 HTTP status codes
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: $.paths.*.delete.responses
    then:
      - field: "@key"
        function: enumeration
        functionOptions:
          values:
            - '200'
            - '204'
            - '400'
            - '401'
            - '403'
            - '404'
            - '500'
            - '503'

  http-status-code-post:
    recommended: true
    description: Post operation can only return 200, 201, 202, 400, 401, 403, 404, and 500 HTTP status codes
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: $.paths.*.post.responses
    then:
      - field: "@key"
        function: enumeration
        functionOptions:
          values:
            - '200'
            - '201'
            - '202'
            - '400'
            - '401'
            - '403'
            - '404'
            - '500'
            - '503'

  http-status-code-post-search:
    recommended: true
    description: Post /search operation can only return 200, 400, 401, 403 and 500 HTTP status codes
    message: "{{description}} ({{path}})"
    severity: error
    tags:
      - http status code
    given: "$.paths[?(/search$/i.test(@property))].post.responses"
    then:
      - field: "@key"
        function: enumeration
        functionOptions:
          values:
            - '200'
            - '400'
            - '401'
            - '403'
            - '404'
            - '500'
            - '503'

  http-status-code-post-unusual-200:
    recommended: true
    description: Post operation which are not /search returning 200 are unusual, did you mean 201 or 202?
    message: "{{description}} ({{path}})"
    severity: info
    tags:
      - http status code
      - manual check
    given: "$.paths[?(!/search$/i.test(@property))].post.responses"
    then:
      - field: "200"
        function: falsy