CommScope Holding API Rules

extends:
  - spectral:oas

# Spectral linting rules for the RUCKUS One API (CommScope).
# Tuned to api.ruckus.cloud conventions: regional servers, JWT bearer
# auth via /oauth2/token, tenant-scoped paths, and asynchronous writes.
rules:
  ruckus-info-contact:
    description: API info must include a contact block.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  ruckus-server-https:
    description: Server URLs must use HTTPS.
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  ruckus-server-host:
    description: Servers should be on the api.*.ruckus.cloud domain.
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "ruckus\\.cloud"

  ruckus-multi-region:
    description: API definition should declare multiple regional servers.
    severity: info
    given: "$.servers"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 2

  ruckus-operation-id:
    description: Every operation must declare a unique operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  ruckus-operation-tags:
    description: Operations must declare at least one tag.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  ruckus-bearer-auth:
    description: API should declare a JWT bearer security scheme.
    severity: error
    given: "$.components.securitySchemes"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            BearerAuth:
              type: object
              properties:
                type:
                  const: http
                scheme:
                  const: bearer
                bearerFormat:
                  const: JWT

  ruckus-tenant-path:
    description: Tenant-scoped resources should use the {tenantId} path parameter.
    severity: info
    given: "$.paths[?(@property.indexOf('tenant') > -1)]"
    then:
      function: pattern
      functionOptions:
        match: "{tenantId}"

  ruckus-async-202:
    description: Write operations should document a 202 Accepted async response.
    severity: info
    given: "$.paths[*][post,put,patch].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ['200']
            - required: ['201']
            - required: ['202']
            - required: ['204']