spectral.yml

extends:
  - ["spectral:oas", recommended]
rules:
  operation-tag-defined: 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:
    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
  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
  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
  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
  common-responses-unauthorized:
    description: Responses should contain common response - 401 (unauthorized)
    message: "{{description}}. Missing {{property}}"
    severity: error
    given: $.paths[?(!@property.match(/well-known/ig))]..responses
    then:
      - field: '401'
        function: truthy
  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[?(!@property.match(/well-known/ig))]~
    then:
      function: pattern
      functionOptions:
        notMatch: \/(get|post|put|patch|delete)(\/|$)
  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
  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[?(!@property.match(/well-known/ig))][get,post,put,delete,patch,options,head,trace]
    then:
      - field: tags
        function: truthy
      - field: tags
        function: length
        functionOptions:
          min: 1
    formats:
      - oas3