SpotHero API Rules

extends: spectral:oas
rules:
  spothero-operation-ids-required:
    description: All operations must have an operationId
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  spothero-operation-summary-required:
    description: All operations must have a summary
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  spothero-operation-summary-title-case:
    description: Operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-z]*(\\s[A-Z][a-z]*)*$"

  spothero-tags-required:
    description: All operations must have at least one tag
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  spothero-response-200-required:
    description: GET operations must have a 200 response
    severity: error
    given: "$.paths[*].get"
    then:
      field: responses.200
      function: truthy

  spothero-response-201-post:
    description: POST operations that create resources should return 201
    severity: warn
    given: "$.paths[*].post"
    then:
      field: responses.201
      function: truthy

  spothero-error-401-required:
    description: All operations must document 401 Unauthorized response
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: responses.401
      function: truthy

  spothero-error-429-required:
    description: All operations must document 429 Too Many Requests response
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: responses.429
      function: truthy

  spothero-path-kebab-case:
    description: Path segments must use kebab-case
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}-]+)+$"

  spothero-api-key-auth:
    description: API must use API key authentication
    severity: error
    given: "$.components.securitySchemes.ApiKeyAuth"
    then:
      function: truthy

  spothero-request-body-content-type:
    description: Request bodies must specify application/json content type
    severity: error
    given: "$.paths[*][post,put,patch].requestBody.content"
    then:
      field: application/json
      function: truthy

  spothero-response-schema-required:
    description: Success responses must include a schema
    severity: warn
    given: "$.paths[*][get,post].responses[200,201].content.application/json"
    then:
      field: schema
      function: truthy

  spothero-parameters-have-descriptions:
    description: Parameters must have descriptions
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].parameters[*]"
    then:
      field: description
      function: truthy

  spothero-schemas-have-descriptions:
    description: Schema properties should have descriptions
    severity: info
    given: "$.components.schemas[*].properties[*]"
    then:
      field: description
      function: truthy