Endpoint API Linting Rules

Schwarz API custom rulesets depend heavily on Spectral OAS Recommended Rules. We consider them to be a very good starting point that we built our custom rules on top of it.

Below you'll find a more semantic description about the API Endpoint rulesets.

---

API Endpoint rules

common-responses-unauthorized

Rule to check if a 401 response is implemented on all paths responses

Severities

• Product API Severity Level: hint
• BFF API Severity Level: hint
• Legacy API Severity Level: hint

common-responses-unauthorized:
  description: Responses should contain common response - 401 (unauthorized)
  message: "{{description}}. Missing {{property}}"
  severity: error
  given: $.paths[?([email protected](/well-known/ig))]..responses
  then:
    - field: '401'
      function: truthy

http-verbs-should-be-used

Rule to check if a resource is implementing all intended HTTP verbs for a data source

Severities

• Product API Severity Level: info
• BFF API Severity Level: info
• Legacy API Severity Level: info

http-verbs-should-be-used:
  description: HTTP verbs should be used to express different actions or functions on a resource
  message: "{{description}}; The HTTP verb {{property}} is missing."
  severity: error
  given: $.paths[?([email protected](/well-known/ig))]
  then:
    - field: get
      function: truthy
    - field: post
      function: truthy
    - field: put
      function: truthy
    - field: patch
      function: truthy
    - field: delete
      function: truthy

must-define-example-schema

Rule to check that every DTO has at least one example

Severities

• Product API Severity Level: warn
• BFF API Severity Level: info
• Legacy API Severity Level: info

must-define-example-schema:
  description: Every DTO must define at least one example
  message: "{{description}}; DTO is lacking an example {{path}}"
  severity: error
  given: $.paths[?([email protected](/well-known/ig))]..content.*
  then:
    - function: xor
      functionOptions:
        properties:
          - example
          - examples

must-have-content-type

Rule to check that every path response has a content type defined

Severities

• Product API Severity Level: warn
• BFF API Severity Level: info
• Legacy API Severity Level: info

must-have-content-type:
  description: Every response must specify its content type
  message: "{{description}}; property {{property}} is missing or not a valid content-type"
  severity: error
  given: $.paths[?([email protected](/well-known/ig))]..content
  then:
    - field: "@key"
      function: truthy
    - field: "@key"
      function: pattern
      functionOptions:
        match: "/"

must-have-response-body

Rule to check that every path with HTTP status code of 200 or 201 has a response body defined

Severities

• Product API Severity Level: warn
• BFF API Severity Level: info
• Legacy API Severity Level: info

must-have-response-body:
  description: Every route returning a http status code of 200 or 201 must have a response body defined
  message: "{{description}}; property {{property}} is missing at path: {{path}}"
  severity: error
  given: $.paths[?([email protected](/well-known/ig))].[?(@property === 'get')].responses[200,201,"200","201"]
  formats:
    - oas3
  then:
    - field: content
      function: truthy
    - field: description
      function: truthy
oas2-must-have-response-body:
  description: Every route returning a http status code of 200 or 201 must have a response body defined
  message: "{{description}}; property {{property}} is missing at path: {{path}}"
  severity: error
  formats:
    - oas2
  given: $.paths[?([email protected](/well-known/ig))].[?(@property === 'get')].responses[200,201,"200","201"]
  then:
    - field: schema
      function: truthy
    - field: description
      function: truthy

no-http-verbs-in-resources

Rule to check misuse of http verbs in url names

Severities

• Product API Severity Level: warn
• BFF API Severity Level: info
• Legacy API Severity Level: info

no-http-verbs-in-resources:
  description: The HTTP Verbs should not be used in the route path to define different actions on a resource
  message: "{{description}}; {{property}} Instead use HTTP verbs to define actions on a resource. Example: PUT - /digital-twin/api/v1/products/42"
  severity: error
  given: $.paths[?([email protected](/well-known/ig))]~
  then:
    function: pattern
    functionOptions:
      notMatch: \/(get|post|put|patch|delete)(\/|$)

path-description-is-mandatory

Rule to check if every path has a description defined

Severities

• Product API Severity Level: warn
• BFF API Severity Level: info
• Legacy API Severity Level: info

path-description-is-mandatory:
  description: Every route of an API should have a description
  message: "{{description}}; property: {{property}} is missing"
  severity: error
  given: $.paths[?([email protected](/well-known/ig))]
  then:
    - field: description
      function: truthy

path-must-specify-tags

Rule to check if every path specifies at least one tag

Severities

• Product API Severity Level: warn
• BFF API Severity Level: info
• Legacy API Severity Level: info

path-must-specify-tags:
  description: Every route must specify at least one tag it belongs to
  message: "{{description}}; property tags is missing at: {{path}}"
  severity: error
  given: $.paths[?([email protected](/well-known/ig))].*
  then:
    - field: tags
      function: truthy
    - field: tags
      function: length
      functionOptions:
        min: 1