reqon-dsl 0.2.0

package/docusaurus/docs/openapi/overview.md

@@ -0,0 +1,212 @@
+---
+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

@@ -0,0 +1,344 @@
+---
+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