.openapirc.yaml

# OpenMorph Default Configuration
# This file demonstrates vendor extension configuration with auto-detection features

# Basic settings
input: ./openapi
backup: true
validate: true

# Key transformations
exclude:
  - x-ignore
  - x-internal # Example of excluding internal extensions
mappings:
  x-operation-group-name: x-fern-sdk-group-name
  x-tag: x-fern-tag
  x-group: x-fern-sdk-group-name # Additional Fern mapping

# Pagination priority (optional - removes lower priority strategies)
pagination_priority:
  - cursor
  - offset
  - page
  - checkpoint
  - none

# Response flattening
flatten_responses: true

# Endpoint-specific pagination rules
# Rules are evaluated in order - first match wins!
endpoint_pagination:
  # Legacy API v1 - use offset pagination for all endpoints
  - endpoint: "/api/v1/*"
    method: "GET"
    pagination: "offset"

  # Analytics endpoints - cursor for real-time performance
  - endpoint: "/api/*/analytics"
    method: "GET"
    pagination: "cursor"

  # High-traffic user feeds - cursor for better scalability
  - endpoint: "/api/v2/users/*/feed"
    method: "GET"
    pagination: "cursor"

  # Search endpoints - page-based for better UX
  - endpoint: "/api/*/search"
    method: "GET"
    pagination: "page"

  # Admin endpoints - no pagination needed
  - endpoint: "/api/admin/*"
    method: "*"
    pagination: "none"

  # Reports - checkpoint for large datasets
  - endpoint: "/api/v2/reports"
    method: "POST"
    pagination: "checkpoint"

  # Specific override for user list (more specific than /api/v1/*)
  # NOTE: This should be placed BEFORE the /api/v1/* rule to take precedence
  # - endpoint: "/api/v1/users"
  #   method: "GET"
  #   pagination: "cursor"

# Vendor extension configuration
vendor_extensions:
  enabled: true
  providers:
    fern:
      extension_name: "x-fern-pagination"
      target_level: "operation" # operation | path | global
      methods: ["get"] # HTTP methods to process
      field_mapping:
        request_params:
          # Auto-maps parameters to template variables
          cursor: ["cursor", "next_cursor", "after"]
          limit: ["limit", "size", "page_size", "per_page", "take"]
          offset: ["offset", "skip"]
          page: ["page", "page_number"]
          # Note: No results field mapping needed - auto-detected from response schemas!
      strategies:
        cursor:
          template:
            type: "cursor"
            cursor_param: "$request.{cursor_param}"
            page_size_param: "$request.{limit_param}"
            results_path: "$response.{results_field}"
          required_fields: ["cursor_param", "results_field"]
        offset:
          template:
            type: "offset"
            offset_param: "$request.{offset_param}"
            limit_param: "$request.{limit_param}"
            results_path: "$response.{results_field}"
          required_fields: ["offset_param", "results_field"]
        page:
          template:
            type: "page"
            page_param: "$request.{page_param}"
            page_size_param: "$request.{limit_param}"
            results_path: "$response.{results_field}"
          required_fields: ["page_param", "results_field"]
        checkpoint:
          template:
            type: "checkpoint"
            cursor_param: "$request.{cursor_param}"
            page_size_param: "$request.{limit_param}"
            results_path: "$response.{results_field}"
          required_fields: ["cursor_param", "results_field"]

# Default values configuration
default_values:
  enabled: true
  rules:
    # Set default values for query parameters
    query_limit_defaults:
      target:
        location: "parameter"
      condition:
        parameter_in: "query"
        type: "integer"
        property_name: "(limit|size|page_size|per_page)"
      value: 20
      priority: 10

    query_sort_defaults:
      target:
        location: "parameter"
      condition:
        parameter_in: "query"
        type: "string"
        property_name: "(sort|order|direction)"
      value: "asc"
      priority: 9

    # Set defaults for boolean properties in components
    boolean_defaults:
      target:
        location: "component"
      condition:
        type: "boolean"
        property_name: "(active|enabled|is_.*)"
      value: true
      priority: 8

    # Set defaults for role/status fields
    role_defaults:
      target:
        location: "component"
      condition:
        type: "string"
        property_name: "role"
      value: "user"
      priority: 7

    status_defaults:
      target:
        location: "component"
      condition:
        type: "string"
        property_name: "status"
      value: "active"
      priority: 6

    # Set defaults for array fields in response schemas
    array_defaults:
      target:
        location: "response"
      condition:
        type: "array"
        http_methods: ["get"]
      value: []
      priority: 5

    # Set defaults for enum fields
    priority_enum_defaults:
      target:
        location: "component"
      condition:
        type: "string"
        property_name: "priority"
        has_enum: true
      value: "medium"
      priority: 4