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

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: $.components.schemas.*
  then:
    - function: xor
      functionOptions:
        properties:
          - example
          - examples

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-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
  formats:
    - oas3
  given: $.paths[?([email protected](/well-known/ig))][get,post,put,delete,patch,options,head,trace]
  then:
    - field: tags
      function: truthy
    - field: tags
      function: length
      functionOptions:
        min: 1