Skip to content

Documentation API Linting Rules

Jump to bottom
Wiki Pipeline edited this page Dec 9, 2022 · 2 revisions

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

API Documentation rules

contact-information

Rule to check if the contact data for the provided API is in place

Severities

  • Product API Severity Level: warn
  • BFF API Severity Level: info
  • Legacy API Severity Level: info
contact-information:
  description: Every API must have a contact containing name, email and a url
  message: "{{description}}; property {{property}} is missing"
  severity: error
  given: $.info.contact
  then:
    - field: name
      function: truthy
    - field: email
      function: truthy
    - field: url
      function: truthy

info-description

Rule to check the global description of the provided API. It must be present and at least 100 characters long.

Severities

  • Product API Severity Level: warn
  • BFF API Severity Level: info
  • Legacy API Severity Level: info
info-description:
  description: Every API must have a global description
  message: "OpenAPI object info `description` must be present and at least 100 chars long."
  severity: error
  given: $.info
  then:
    - field: description
      function: truthy
    - field: description
      function: length
      functionOptions:
        min: 100
Clone this wiki locally