Rundeck API Rules

extends: spectral:oas
rules:

  # Rundeck API conventions: all paths under /api/N/ versioning
  rundeck-operation-id-required:
    description: All operations must have an operationId for code generation
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  rundeck-operation-id-camel-case:
    description: >-
      Rundeck operationIds use camelCase convention (e.g., listJobs, runJob,
      getExecution). This ensures consistent client SDK method naming.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

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

  rundeck-tags-title-case:
    description: Tags must use Title Case (e.g., "Jobs", "Executions", "Projects")
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].tags[*]"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z ]+$"

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

  rundeck-summary-title-case:
    description: >-
      Operation summaries must use Title Case (e.g., "List Jobs", "Run Job",
      "Get Execution Status"). This matches Rundeck's documentation style.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]+$"

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

  rundeck-responses-must-include-401:
    description: >-
      Rundeck API requires authentication on all protected endpoints.
      Operations must document the 401 Unauthorized response.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "401"
      function: truthy

  rundeck-get-must-return-200:
    description: GET operations must define a 200 success response
    severity: error
    given: "$.paths[*].get.responses"
    then:
      field: "200"
      function: truthy

  rundeck-delete-must-return-204:
    description: DELETE operations should return 204 No Content
    severity: warn
    given: "$.paths[*].delete.responses"
    then:
      field: "204"
      function: truthy

  rundeck-post-must-return-200-or-201:
    description: POST operations must return either 200 or 201
    severity: warn
    given: "$.paths[*].post.responses"
    then:
      function: schema
      functionOptions:
        schema:
          oneOf:
            - required: ["200"]
            - required: ["201"]

  rundeck-project-path-parameter:
    description: >-
      Path operations containing {project} must have the project parameter documented.
      Rundeck organizes most resources under projects.
    severity: error
    given: "$.paths[~/project/~][*].parameters[?(@.name == 'project')]"
    then:
      field: required
      function: truthy

  rundeck-execution-id-path-parameter:
    description: Path operations with {id} for executions must mark id as required
    severity: error
    given: "$.paths[~/execution/~][*].parameters[?(@.name == 'id')]"
    then:
      field: required
      function: truthy

  rundeck-token-auth-header-name:
    description: >-
      Rundeck uses X-Rundeck-Auth-Token header for API token authentication.
      Security schemes should reference this header name.
    severity: warn
    given: "$.components.securitySchemes[?(@.type == 'apiKey')].name"
    then:
      function: pattern
      functionOptions:
        match: "^X-Rundeck-Auth-Token$"

  rundeck-schema-type-required:
    description: All schema properties should have a type defined
    severity: warn
    given: "$.components.schemas[*].properties[*]"
    then:
      field: type
      function: truthy

  rundeck-response-content-type-json:
    description: API responses should use application/json content type
    severity: warn
    given: "$.paths[*][get,post,put].responses[200,201].content"
    then:
      field: "application/json"
      function: truthy

  rundeck-info-contact-required:
    description: API info must include contact information
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy

  rundeck-servers-defined:
    description: At least one server must be defined
    severity: error
    given: "$"
    then:
      field: servers
      function: truthy