@stackwright-pro/openapi

Transform OpenAPI specifications into type-safe, runtime-validated Stackwright applications

"Point at an API spec, get production-ready code in minutes, not weeks"

Overview

@stackwright-pro/openapi is the cornerstone of Stackwright Pro's value proposition: automatic code generation from OpenAPI 3.x specifications. It generates Zod validation schemas, TypeScript types, typed API clients, and Stackwright CollectionProviders - all with mathematical correctness guarantees.

For government and enterprise teams: This means taking existing API specifications (which you already have) and getting type-safe, runtime-validated UIs without manual coding. Hours to first working application. Days to production deployment.

What Gets Generated

From a single OpenAPI spec, this package generates:

1. Zod Validation Schemas - Runtime validation that can't be bypassed
2. TypeScript Types - Compile-time type safety
3. CollectionProviders - Integration with Stackwright content system
4. Typed API Clients - Fully typed fetch functions (coming soon)

All code is generated at build time via the prebuild plugin system.

Installation

# Private package - contact Per Aspera LLC for access
pnpm add @stackwright-pro/openapi

# Peer dependencies (already in Stackwright projects)
pnpm add @stackwright/types @stackwright/build-scripts zod

Quick Start

1. Configure Integration

Add to your stackwright.yml:

theme:
  id: my-app
  name: My Application

integrations:
  - type: openapi
    name: logistics
    spec: ./specs/logistics-api.yaml
    auth:
      type: bearer
      token: $API_TOKEN
    collections:
      - endpoint: /equipment
        slug_field: id
      - endpoint: /supplies  
        slug_field: id

2. Register Plugin

Create scripts/prebuild.js:

const { runPrebuild } = require('@stackwright/build-scripts');
const { createOpenAPIPlugin } = require('@stackwright-pro/openapi');

async function main() {
  await runPrebuild({
    plugins: [createOpenAPIPlugin()],
  });
}

main().catch(console.error);

Update package.json:

{
  "scripts": {
    "prebuild": "node scripts/prebuild.js",
    "predev": "node scripts/prebuild.js",
    "dev": "next dev",
    "build": "next build"
  }
}

3. Generate Code

pnpm prebuild

This generates code to src/generated/logistics/:

• schemas.ts - Zod validation schemas
• types.ts - TypeScript type definitions
• provider.ts - CollectionProvider implementations
• client.ts - Typed API client (coming soon)

4. Use Generated Code

import { EquipmentSchema } from '@/generated/logistics/schemas';
import type { Equipment } from '@/generated/logistics/types';

// Runtime validation (mathematically proven safe)
const validated = EquipmentSchema.parse(untrustedData);

// Compile-time type safety
const equipment: Equipment = {
  id: '123',
  name: 'HMMWV',
  status: 'operational', // TypeScript error if invalid
};

5. Integrate with Stackwright

The generated CollectionProvider automatically integrates with Stackwright:

# pages/equipment/content.yml
content:
  content_items:
    - type: collection_list
      label: equipment-list
      source: logistics-equipment  # Auto-generated from OpenAPI
      card:
        heading: "{{name}}"
        description: "{{description}}"
        metadata:
          - label: "Status"
            value: "{{status}}"

Architecture

The Zod Schema Generator (Core Engine)

The ZodSchemaGenerator is the mathematical proof engine that ensures runtime validation:

Supported OpenAPI Features:

• ✅ All primitive types (string, number, boolean, integer, null)
• ✅ Objects (required/optional properties, additionalProperties)
• ✅ Arrays (with item validation, constraints)
• ✅ Enums (string and number)
• ✅ String formats (email, url, uuid, date-time, date, time, ipv4, ipv6)
• ✅ Number constraints (minimum, maximum, multipleOf, exclusiveMinimum/Maximum)
• ✅ String constraints (minLength, maxLength, pattern regex)
• ✅ Array constraints (minItems, maxItems, uniqueItems)
• ✅ Object constraints (minProperties, maxProperties)
• ✅ Composition (allOf, oneOf, anyOf)
• ✅ $ref resolution (local and external references)
• ✅ Nullable types (nullable: true or type: ["string", "null"])
• ✅ Default values
• ✅ Read-only and write-only properties

27 comprehensive tests ensure correctness.

The OpenAPI Parser

Parses OpenAPI 3.0.x and 3.1.x specifications:

• Supports local files and remote URLs
• Validates spec structure
• Extracts paths, schemas, operations
• Resolves $ref pointers (including circular references)

The Type Generator

Converts OpenAPI schemas to TypeScript interfaces:

• Proper optional vs required property handling
• Union types for oneOf/anyOf
• Intersection types for allOf
• Type inference from Zod schemas

The CollectionProvider Generator

Generates typed Stackwright CollectionProviders:

• Fetches data from API endpoints
• Applies schema validation automatically
• Handles authentication (bearer, apiKey)
• Error handling and retries
• Integrates with Stackwright content system

The Prebuild Plugin

Runs automatically during pnpm dev and pnpm build:

• Reads integration config from stackwright.yml
• Parses OpenAPI specs
• Generates all code files
• Writes to src/generated/{integrationName}/

Authentication

Bearer Token

integrations:
  - type: openapi
    name: api
    spec: ./spec.yaml
    auth:
      type: bearer
      token: $API_TOKEN  # Environment variable

API Key

integrations:
  - type: openapi
    name: api
    spec: ./spec.yaml
    auth:
      type: apiKey
      name: X-API-Key
      in: header  # or 'query'
      value: $API_KEY

OAuth2 (Coming Soon)

OAuth2 flows will be supported in a future release.

Collections

Map OpenAPI endpoints to Stackwright collections:

integrations:
  - type: openapi
    name: logistics
    spec: ./specs/logistics-api.yaml
    collections:
      - endpoint: /equipment
        method: get  # default
        slug_field: id
        
      - endpoint: /supplies
        slug_field: item_id
        
      - endpoint: /personnel
        slug_field: employee_id

Each collection generates:

• Zod schema for validation
• TypeScript type for compile-time safety
• CollectionProvider for data fetching

Examples

Government Logistics API

See examples/marine-logistics-demo/ for a complete working example integrating with a Marine Corps logistics API.

E-Commerce Product Catalog

integrations:
  - type: openapi
    name: products
    spec: https://api.example.com/openapi.json
    auth:
      type: bearer
      token: $SHOPIFY_TOKEN
    collections:
      - endpoint: /products
        slug_field: sku

Multi-API Integration

integrations:
  - type: openapi
    name: users
    spec: ./specs/users-api.yaml
    collections:
      - endpoint: /users
        slug_field: id
        
  - type: openapi
    name: orders
    spec: ./specs/orders-api.yaml
    collections:
      - endpoint: /orders
        slug_field: order_id

API Reference

OpenAPIPlugin

import { createOpenAPIPlugin } from '@stackwright-pro/openapi';

const plugin = createOpenAPIPlugin();

await runPrebuild({
  plugins: [plugin],
});

OpenAPIParser

import { OpenAPIParser } from '@stackwright-pro/openapi';

const parser = new OpenAPIParser();
const { document } = await parser.parse('./spec.yaml');

ZodSchemaGenerator

import { ZodSchemaGenerator } from '@stackwright-pro/openapi';

const generator = new ZodSchemaGenerator();
const zodCode = generator.generate(schema, { schemaName: 'UserSchema' });

TypeGenerator

import { TypeGenerator } from '@stackwright-pro/openapi';

const generator = new TypeGenerator();
const typeCode = generator.generate(schema, { typeName: 'User' });

CollectionProviderGenerator

import { CollectionProviderGenerator } from '@stackwright-pro/openapi';

const generator = new CollectionProviderGenerator(openAPIDocument);
const providerCode = generator.generate(collectionConfig);

Testing

The package includes comprehensive test coverage:

cd packages/openapi
pnpm test

Test suites:

• parser.test.ts - OpenAPI parsing and $ref resolution
• zod-generator.test.ts - 27 tests covering all schema features
• type-generator.test.ts - TypeScript type generation
• collection-provider-generator.test.ts - Provider generation
• prebuild-plugin.test.ts - Plugin integration

Troubleshooting

"Integration not found in stackwright.yml"

Ensure your integrations section is at the root level of stackwright.yml, not nested under theme or other properties.

"Failed to parse OpenAPI spec"

• Validate your spec at https://editor.swagger.io
• Ensure the spec version is 3.0.x or 3.1.x (not Swagger 2.0)
• Check for $ref resolution errors

"Generated code not found"

• Verify pnpm prebuild runs successfully
• Check src/generated/{integrationName}/ exists
• Ensure build scripts are configured in package.json

TypeScript errors in generated code

• Run pnpm build:openapi to regenerate
• Check for breaking changes in your OpenAPI spec
• Verify zod is installed as a dependency

License

Proprietary - Commercial license. See LICENSE for terms.

The open-source Stackwright framework is MIT licensed at github.com/Per-Aspera-LLC/stackwright.

Support

For enterprise support, custom integrations, or government procurement inquiries:

• Email: [email protected]
• GitHub Issues: stackwright-pro/issues
• Documentation: stackwright-pro/docs

Built by Per Aspera LLC
"Through hardship to the stars"