Subex API Rules

extends: spectral:oas
rules:
  subex-operation-id-required:
    description: All Subex API operations must have an operationId
    message: "Operation at '{{path}}' is missing operationId"
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: error
    then:
      field: operationId
      function: truthy

  subex-operation-id-camel-case:
    description: Subex operationIds use camelCase
    message: "operationId '{{value}}' should use camelCase"
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  subex-tags-required:
    description: All operations should have at least one tag
    message: "Operation at '{{path}}' should include tags"
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: warn
    then:
      field: tags
      function: truthy

  subex-bearer-auth:
    description: Subex API uses Bearer token authentication
    message: "API must define a BearerAuth security scheme"
    given: "$.components.securitySchemes"
    severity: error
    then:
      field: BearerAuth
      function: truthy

  subex-response-200:
    description: GET operations must define a 200 response
    message: "GET operation at '{{path}}' must define a 200 response"
    given: "$.paths[*].get.responses"
    severity: warn
    then:
      field: "200"
      function: truthy

  subex-pagination-params:
    description: List operations should support pagination parameters
    message: "List operation at '{{path}}' should include page/size parameters"
    given: "$.paths[*].get"
    severity: hint
    then:
      field: parameters
      function: truthy

  subex-error-401-defined:
    description: Operations should define a 401 unauthorized response
    message: "Operation should define a 401 response"
    given: "$.paths[*][get,post,put,patch,delete].responses"
    severity: hint
    then:
      field: "401"
      function: truthy

  subex-servers-defined:
    description: API must define servers
    message: "API must define at least one server"
    given: "$"
    severity: error
    then:
      field: servers
      function: truthy

  subex-info-contact:
    description: API should include contact information
    message: "API info must include contact details"
    given: "$.info"
    severity: warn
    then:
      field: contact
      function: truthy