Remote API Rules

extends:
  - spectral:oas
rules:
  remote-info-title-must-include-remote:
    description: Every Remote OpenAPI spec title must start with "Remote".
    severity: error
    given: "$.info.title"
    then:
      function: pattern
      functionOptions:
        match: '^Remote '

  remote-server-must-be-gateway-remote:
    description: Production server must be the Remote API gateway.
    severity: error
    given: "$.servers[?(@.description == 'Production')].url"
    then:
      function: pattern
      functionOptions:
        match: '^https://gateway\.remote\.com'

  remote-sandbox-server-must-be-gateway-sandbox:
    description: Sandbox server must be the Remote sandbox gateway.
    severity: warn
    given: "$.servers[?(@.description == 'Sandbox')].url"
    then:
      function: pattern
      functionOptions:
        match: '^https://gateway\.remote-sandbox\.com'

  remote-summary-must-be-title-case:
    description: Operation summaries must use Title Case.
    severity: warn
    given: "$.paths.*.*.summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z]([A-Za-z0-9]*)(\\s+[A-Z][A-Za-z0-9]*|\\s+(A|An|And|At|But|By|For|In|Of|On|Or|The|To|With)\\b)*\\s*$"

  remote-paths-must-be-snake-case:
    description: Remote paths use snake_case for resource segments.
    severity: error
    given: "$.paths"
    then:
      field: '@key'
      function: pattern
      functionOptions:
        match: '^(/(v1|oauth|oauth2)(/[a-z0-9_]+(\\{[a-z_]+\\})?)*)?$'

  remote-must-use-bearer-auth:
    description: Remote APIs (except OAuth endpoints) must declare BearerAuth security.
    severity: warn
    given: "$.components.securitySchemes.BearerAuth"
    then:
      function: truthy

  remote-error-responses-required:
    description: Operations must declare 401 and 429 responses.
    severity: warn
    given: "$.paths..responses"
    then:
      - field: "401"
        function: truthy
      - field: "429"
        function: truthy

  remote-no-trailing-slash:
    description: Paths must not end with a trailing slash.
    severity: error
    given: "$.paths"
    then:
      field: '@key'
      function: pattern
      functionOptions:
        notMatch: '.+/$'

  remote-uuid-path-params:
    description: Path parameters ending in "_id" must declare uuid format.
    severity: warn
    given: "$.paths..parameters[?(@.in == 'path' && @.name =~ /_id$/)].schema"
    then:
      field: format
      function: enumeration
      functionOptions:
        values: [uuid]

  remote-tag-must-be-title-case:
    description: Tags must use Title Case.
    severity: warn
    given: "$.tags[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][A-Za-z0-9]*(\\s+[A-Z][A-Za-z0-9]*)*$"