Trioptima API Rules

extends: spectral:oas
rules:
  # triReduce API paths must use /api/v1/ prefix
  trioptima-path-api-versioned:
    description: All triReduce API paths must start with /api/v1/ or /v1/
    message: "Path '{{property}}' must start with /api/v1/ or /v1/"
    given: "$.paths[*]~"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^/(api/v1|v1)/"

  # All operations must have operationIds
  trioptima-operation-must-have-id:
    description: All operations must have an operationId
    message: "Operation at '{{path}}' is missing an operationId"
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: error
    then:
      field: operationId
      function: truthy

  # Operation summaries must use Title Case
  trioptima-summary-title-case:
    description: Operation summaries must use Title Case
    message: "Summary '{{value}}' should use Title Case"
    given: "$.paths[*][*].summary"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]+$"

  # POST/PUT operations must have request body
  trioptima-mutation-must-have-body:
    description: POST and PUT operations should have a requestBody defined
    message: "POST/PUT operation at '{{path}}' is missing a requestBody"
    given: "$.paths[*][post,put]"
    severity: warn
    then:
      field: requestBody
      function: truthy

  # Security must be defined for all operations (authenticated API)
  trioptima-operation-must-be-secured:
    description: All operations must reference an OAuth 2.0 security scheme
    message: "Operation at '{{path}}' must define security requirements"
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: warn
    then:
      function: schema
      functionOptions:
        schema:
          oneOf:
            - required: ["security"]
            - properties: {}

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

  # All operations must have 401 response defined
  trioptima-must-have-401-response:
    description: All operations must document 401 Unauthorized response
    message: "Operation is missing 401 response definition"
    given: "$.paths[*][get,post,put,patch,delete].responses"
    severity: warn
    then:
      field: "401"
      function: truthy