reqon-dsl 0.2.0 → 0.3.0

package/docusaurus/docs/openapi/overview.md

@@ -1,212 +0,0 @@
----
-sidebar_position: 1
----
-
-# OpenAPI Integration Overview
-
-Reqon integrates with OpenAPI (Swagger) specifications for type-safe API calls and response validation.
-
-## Benefits
-
-- **Type-safe operations**: Call APIs by operation ID
-- **Auto-discovery**: Base URL and endpoints from spec
-- **Response validation**: Validate against schema definitions
-- **Documentation sync**: API changes reflected automatically
-
-## Quick Start
-
-### 1. Define Source from Spec
-
-```vague
-source Petstore from "./petstore.yaml" {
-  auth: bearer,
-  validateResponses: true
-}
-```
-
-### 2. Call Operations
-
-```vague
-action FetchPets {
-  call Petstore.listPets { params: { limit: 100 } }
-  store response -> pets { key: .id }
-
-  call Petstore.getPetById { params: { petId: "123" } }
-  store response -> petDetails { key: .id }
-}
-```
-
-## How It Works
-
-### Loading Specs
-
-Reqon loads and parses OpenAPI specs:
-
-```vague
-// Local file
-source API from "./api.yaml" { auth: bearer }
-
-// URL
-source API from "https://api.example.com/openapi.json" { auth: bearer }
-```
-
-### Operation Resolution
-
-Reqon maps `call Source.operationId` to:
-
-```yaml
-# OpenAPI spec
-paths:
-  /pets:
-    get:
-      operationId: listPets
-      # Reqon uses: GET /pets
-```
-
-### Base URL Extraction
-
-Base URL from spec's `servers`:
-
-```yaml
-servers:
-  - url: https://api.example.com/v1
-```
-
-## Configuration Options
-
-```vague
-source API from "./spec.yaml" {
-  auth: bearer,
-  validateResponses: true,  # Validate responses against schema
-  headers: {                # Additional headers
-    "X-Custom": "value"
-  }
-}
-```
-
-## Example Workflow
-
-```vague
-mission PetstoreSync {
-  source Petstore from "./petstore.yaml" {
-    auth: api_key,
-    validateResponses: true
-  }
-
-  store pets: file("pets")
-
-  action SyncPets {
-    // List all pets
-    call Petstore.listPets {
-      params: { limit: 100 }
-    }
-
-    for pet in response {
-      // Get full details
-      call Petstore.getPetById {
-        params: { petId: pet.id }
-      }
-
-      store response -> pets { key: .id }
-    }
-  }
-
-  action CreatePet {
-    call Petstore.addPet {
-      body: {
-        name: "Fluffy",
-        tag: "cat"
-      }
-    }
-  }
-
-  run SyncPets
-}
-```
-
-## Comparison: Traditional vs OAS
-
-### Traditional Approach
-
-```vague
-source API { auth: bearer, base: "https://api.example.com" }
-
-action Fetch {
-  get "/pets"
-  get concat("/pets/", id)
-}
-```
-
-### OAS Approach
-
-```vague
-source API from "./spec.yaml" { auth: bearer }
-
-action Fetch {
-  call API.listPets
-  call API.getPetById { params: { petId: id } }
-}
-```
-
-### Benefits of OAS
-
-| Aspect | Traditional | OAS |
-|--------|-------------|-----|
-| Type safety | None | Schema validation |
-| Endpoint updates | Manual | Automatic |
-| Documentation | Separate | Integrated |
-| IDE support | Limited | Full autocomplete |
-
-## Supported Spec Formats
-
-- OpenAPI 3.0.x (recommended)
-- OpenAPI 3.1.x
-- Swagger 2.0 (converted internally)
-
-### Format Detection
-
-```vague
-// YAML
-source API from "./spec.yaml"
-
-// JSON
-source API from "./spec.json"
-
-// Remote
-source API from "https://api.example.com/openapi.json"
-```
-
-## Common Patterns
-
-### Fetch with Pagination
-
-```vague
-call API.listItems {
-  params: { limit: 100 },
-  paginate: cursor(cursor, 100, "nextCursor"),
-  until: response.nextCursor == null
-}
-```
-
-### Conditional Operations
-
-```vague
-action SyncItem {
-  call API.getItem { params: { id: itemId } }
-
-  match response {
-    { exists: false } -> {
-      call API.createItem { body: itemData }
-    },
-    _ -> {
-      call API.updateItem { params: { id: itemId }, body: itemData }
-    }
-  }
-}
-```
-
-## Next Steps
-
-- [Loading Specs](./loading-specs) - Loading and caching specs
-- [Operation Calls](./operation-calls) - Calling operations
-- [Response Validation](./response-validation) - Validating responses

package/docusaurus/docs/openapi/response-validation.md

@@ -1,344 +0,0 @@
----
-sidebar_position: 4
----
-
-# Response Validation
-
-Reqon can validate API responses against OpenAPI schema definitions.
-
-## Enabling Validation
-
-```vague
-source API from "./spec.yaml" {
-  auth: bearer,
-  validateResponses: true
-}
-```
-
-## How It Works
-
-### Schema Matching
-
-OpenAPI spec:
-```yaml
-paths:
-  /pets/{petId}:
-    get:
-      operationId: getPetById
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Pet'
-
-components:
-  schemas:
-    Pet:
-      type: object
-      required:
-        - id
-        - name
-      properties:
-        id:
-          type: string
-        name:
-          type: string
-        tag:
-          type: string
-```
-
-Reqon validates:
-```vague
-call API.getPetById { params: { petId: "123" } }
-// Validates response against Pet schema
-```
-
-## Validation Modes
-
-### Strict Mode
-
-Fails on schema mismatch:
-
-```vague
-source API from "./spec.yaml" {
-  validateResponses: true,
-  validationMode: "strict"
-}
-```
-
-### Warning Mode
-
-Logs warning but continues:
-
-```vague
-source API from "./spec.yaml" {
-  validateResponses: true,
-  validationMode: "warn"
-}
-```
-
-### Off
-
-No validation (default):
-
-```vague
-source API from "./spec.yaml" {
-  validateResponses: false
-}
-```
-
-## Validation Rules
-
-### Required Fields
-
-```yaml
-Pet:
-  required:
-    - id
-    - name
-```
-
-Response missing `name` triggers error:
-```json
-{ "id": "123" }  // Error: missing required field 'name'
-```
-
-### Type Checking
-
-```yaml
-Pet:
-  properties:
-    id:
-      type: string
-    age:
-      type: integer
-```
-
-```json
-{ "id": 123, "age": "five" }
-// Errors: id should be string, age should be integer
-```
-
-### Enum Validation
-
-```yaml
-Pet:
-  properties:
-    status:
-      type: string
-      enum: [available, pending, sold]
-```
-
-```json
-{ "status": "active" }  // Error: status not in enum
-```
-
-### Array Validation
-
-```yaml
-Pets:
-  type: array
-  items:
-    $ref: '#/components/schemas/Pet'
-```
-
-Each item in array is validated.
-
-## Error Handling
-
-### With Validation Errors
-
-```vague
-call API.getPet { params: { id: "123" } }
-
-match response {
-  { validationErrors: errors } -> {
-    store {
-      operation: "getPet",
-      errors: errors
-    } -> validationFailures
-    skip
-  },
-  _ -> store response -> pets { key: .id }
-}
-```
-
-### Catching Specific Errors
-
-```vague
-match response {
-  { validationErrors: e } where includes(e, "missing required") -> {
-    // Handle missing fields
-    abort "Incomplete data from API"
-  },
-  { validationErrors: e } where includes(e, "type mismatch") -> {
-    // Handle type issues
-    store response -> typeIssues { key: response.id }
-    skip
-  },
-  _ -> continue
-}
-```
-
-## Custom Validation
-
-### Additional Constraints
-
-Beyond schema validation:
-
-```vague
-call API.getOrder { params: { id: orderId } }
-
-// Schema validation happens automatically
-
-// Additional business validation
-validate response {
-  assume .total >= 0,
-  assume .items is array,
-  assume length(.items) > 0,
-  assume .status != "invalid"
-}
-
-store response -> orders { key: .id }
-```
-
-### Combining Validations
-
-```vague
-action ValidatedFetch {
-  call API.listItems
-
-  for item in response.items {
-    // Schema already validated by OAS
-
-    // Additional validation
-    validate item {
-      assume .price > 0,
-      assume .quantity >= 0
-    }
-
-    match item {
-      _ where .validationErrors != null -> {
-        queue invalid { item: item }
-        skip
-      },
-      _ -> store item -> items { key: .id }
-    }
-  }
-}
-```
-
-## Schema References
-
-### Component Schemas
-
-```yaml
-components:
-  schemas:
-    Pet:
-      type: object
-      properties:
-        id: { type: string }
-        owner:
-          $ref: '#/components/schemas/Owner'
-    Owner:
-      type: object
-      properties:
-        name: { type: string }
-```
-
-Nested schemas are validated:
-
-```json
-{
-  "id": "123",
-  "owner": {
-    "name": 123  // Error: name should be string
-  }
-}
-```
-
-### OneOf/AnyOf
-
-```yaml
-Response:
-  oneOf:
-    - $ref: '#/components/schemas/Success'
-    - $ref: '#/components/schemas/Error'
-```
-
-Validates against matching schema.
-
-## Best Practices
-
-### Use Validation in Development
-
-```vague
-source API from "./spec.yaml" {
-  validateResponses: env("NODE_ENV") != "production"
-}
-```
-
-### Log Validation Failures
-
-```vague
-match response {
-  { validationErrors: e } -> {
-    store {
-      timestamp: now(),
-      operation: currentOperation,
-      errors: e,
-      response: response
-    } -> validationLog
-  },
-  _ -> continue
-}
-```
-
-### Keep Specs Updated
-
-Ensure spec matches actual API:
-- Run validation in CI/CD
-- Update spec when API changes
-- Use spec versioning
-
-### Handle Gracefully
-
-```vague
-// Don't fail hard on validation
-source API from "./spec.yaml" {
-  validateResponses: true,
-  validationMode: "warn"
-}
-
-// Handle in code
-match response {
-  { validationErrors: _ } -> {
-    // Log and continue with caution
-  },
-  _ -> continue
-}
-```
-
-## Troubleshooting
-
-### "Schema not found"
-
-Check component name matches:
-
-```yaml
-$ref: '#/components/schemas/Pet'  # Case sensitive
-```
-
-### False Positives
-
-Schema may be outdated:
-- Update spec from API provider
-- Check for API version changes
-
-### Performance
-
-Validation adds overhead:
-- Disable in production if not needed
-- Use sampling for high-volume APIs