SmartRecruiters API Rules

extends: spectral:oas
rules:
  smartrecruiters-operation-tags:
    description: All operations must have at least one tag for grouping
    severity: warn
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy

  smartrecruiters-operation-ids:
    description: All operations must have an operationId in camelCase
    severity: error
    given: "$.paths[*][*]"
    then:
      field: operationId
      function: truthy

  smartrecruiters-summary-title-case:
    description: Operation summaries must use Title Case
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]*$"

  smartrecruiters-pagination-params:
    description: List operations should support limit and offset pagination parameters
    severity: warn
    given: "$.paths[*].get"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            parameters:
              type: array
              contains:
                type: object
                properties:
                  name:
                    enum: [limit, offset]

  smartrecruiters-list-result-wrapper:
    description: >-
      List endpoints should return a ListResult wrapper with limit, offset,
      totalFound, and content fields
    severity: warn
    given: "$.paths[*].get.responses.200.content['application/json'].schema"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            '$ref':
              type: string

  smartrecruiters-company-identifier-path:
    description: >-
      Paths that access company-scoped resources must include companyIdentifier
      path parameter
    severity: warn
    given: "$.paths['/v1/companies/{companyIdentifier}/*']"
    then:
      function: truthy

  smartrecruiters-error-responses:
    description: All operations must define 401 and 403 error responses
    severity: error
    given: "$.paths[*][post,put,patch,delete]"
    then:
      field: responses
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - '401'
            - '403'

  smartrecruiters-content-type:
    description: Request bodies must use application/json content type
    severity: error
    given: "$.paths[*][post,put,patch].requestBody.content"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required:
            - 'application/json'

  smartrecruiters-security-scheme:
    description: API must define authentication security schemes (ApiKey or OAuth2)
    severity: error
    given: "$.components.securitySchemes"
    then:
      function: truthy

  smartrecruiters-no-trailing-slashes:
    description: API paths must not have trailing slashes
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        notMatch: "/$"