R API Rules

extends: spectral:oas
rules:
  r-operation-summary-title-case:
    description: All operation summaries must use Title Case
    message: "Operation summary '{{value}}' 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]*)*$"

  r-tags-title-case:
    description: All tags must use Title Case
    message: "Tag '{{value}}' must use Title Case"
    severity: warn
    given: "$.paths[*][*].tags[*]"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*(\\s[A-Z][a-zA-Z0-9]*)*$"

  r-operation-ids-must-be-camel-case:
    description: Operation IDs must use camelCase
    message: "Operation ID '{{value}}' must use camelCase"
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  r-paths-kebab-case:
    description: Path segments must use kebab-case
    message: "Path segment must use kebab-case (no underscores or uppercase)"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        notMatch: "[A-Z_]"

  r-responses-must-include-success:
    description: All operations must define at least one 2xx response
    message: "Operation must define a 2xx success response"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: responses
      function: schema
      functionOptions:
        schema:
          type: object
          minProperties: 1

  r-parameters-must-have-descriptions:
    description: All parameters must have descriptions
    message: "Parameter '{{value}}' must have a description"
    severity: warn
    given: "$.paths[*][*].parameters[*]"
    then:
      field: description
      function: truthy

  r-components-schemas-pascal-case:
    description: Schema component names must use PascalCase
    message: "Schema name '{{value}}' must use PascalCase"
    severity: warn
    given: "$.components.schemas[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*$"