Storyblok API Rules

extends: spectral:oas
rules:
  storyblok-space-id-path-param:
    description: Management API endpoints must include space_id as a path parameter
    message: "Management API path '{{path}}' should include {space_id} parameter"
    severity: warn
    given: "$.paths[?(@property.match(/\\/spaces\\//))].*.parameters[?(@.in == 'path')]"
    then:
      field: name
      function: defined

  storyblok-https-only:
    description: All server URLs must use HTTPS
    message: "Server URL must use HTTPS"
    severity: error
    given: "$.servers[*]"
    then:
      field: url
      function: pattern
      functionOptions:
        match: "^https://"

  storyblok-operation-ids:
    description: All operations must have an operationId
    message: "Operation at '{{path}}' must have an operationId"
    severity: error
    given: "$.paths.*.*"
    then:
      field: operationId
      function: truthy

  storyblok-operation-summary:
    description: All operations must have a summary
    message: "Operation at '{{path}}' must have a summary"
    severity: warn
    given: "$.paths.*.*"
    then:
      field: summary
      function: truthy

  storyblok-tags-required:
    description: All operations must have at least one tag
    message: "Operation must include at least one tag"
    severity: warn
    given: "$.paths.*.*"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  storyblok-401-response:
    description: All operations should define a 401 Unauthorized response
    message: "Operation should define a 401 response for unauthorized access"
    severity: warn
    given: "$.paths.*.*.responses"
    then:
      field: "401"
      function: defined

  storyblok-json-content-type:
    description: POST and PUT operations must accept application/json content type
    message: "POST/PUT operation should accept application/json"
    severity: warn
    given: "$.paths.*[post,put].requestBody.content"
    then:
      field: "application/json"
      function: defined

  storyblok-pagination-params:
    description: List operations should support pagination parameters
    message: "List operation should include 'page' and 'per_page' parameters"
    severity: info
    given: "$.paths[?(@property.match(/stories$|components$|assets$|datasources$|collaborators$/))].get.parameters[*]"
    then:
      field: name
      function: defined

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

  storyblok-version-in-server:
    description: Server URLs should include API version
    message: "Server URL should include version path component"
    severity: info
    given: "$.servers[*]"
    then:
      field: url
      function: pattern
      functionOptions:
        match: "/v[0-9]"