General 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 General rulesets.

---

API General rules

must-have-path

Rule to check if the given API spec does have at least one path defined

Severities

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

must-have-path:
  description: Every API must have at least one path
  message: "{{description}}; property `paths` is empty"
  severity: error
  given: $
  then:
    - field: paths
      function: length
      functionOptions:
        min: 1

operation-tag-defined

The Rule "operation-tag-defined" from the spectral:oas recommended ruleset was disabled

Severities

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

operation-tag-defined: off

path-must-match-api-standards

Used to check if provided paths stick to API best practices Status: DEACTIVATED - in discussion

Severities

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

path-must-match-api-standards:
  description: API Path must match company API uri standards
  message: "{{description}}; {{property}} incorrect. Example: /digital-twin/api/v1/products"
  severity: error
  resolved: false
  given: $.paths[?(!@property.match(/well-known/ig))~]
  then:
    function: pattern
    functionOptions:
      match: ^\/([a-z-]+)\/api\/(v[1-9])\/([a-z]+(\w+s\b.*))

servers-must-match-api-standards

Rule to check if provided server urls stick to the API best practices Status: DEACTIVATED - in discussion

Severities

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

servers-must-match-api-standards:
  description: Schema and host in URL must match company API standards
  message: "{{description}}; {{property}}:{{value}} incorrect. Example: https://live.api.schwarz/digital-twin/api/v1/products"
  severity: error
  resolved: false
  given: "$.servers..url"
  then:
    function: pattern
    functionOptions:
      match: ^((http[s]?):\/\/)([a-z]+)([.+])api.schwarz