OpenAPI SDK Generation

Moose automatically generates OpenAPI specifications for all your APIs, enabling you to create type-safe client SDKs in any language. This allows you to integrate your Moose APIs into any application with full type safety and IntelliSense support.

Overview

When you run moose dev, Moose automatically generates an OpenAPI specification file at .moose/openapi.yaml that includes:

All ingestion endpoints with request/response schemas
All consumption APIs with query parameters and response types
Example data for testing and documentation
Type definitions for all data models

Generating SDKs

Prerequisites

Install OpenAPI Generator CLI:

npm install -g @openapitools/openapi-generator-cli

Start your Moose dev server:
```
moose dev
```
Locate your OpenAPI spec: The specification is automatically generated at .moose/openapi.yaml

TypeScript SDK Generation

Generate a TypeScript SDK using the fetch client:

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g typescript-fetch \
  -o ./generated-client

Python SDK Generation

Generate a Python SDK:

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g python \
  -o ./generated-client

JavaScript SDK Generation

Generate a JavaScript SDK:

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g javascript \
  -o ./generated-client

Integration Examples

TypeScript Integration

Python Integration

Available Generators

OpenAPI Generator supports 50+ languages and frameworks. Popular options include:

TypeScript

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g typescript-fetch \
  -o ./generated-client

Python

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g python \
  -o ./generated-client

JavaScript

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g javascript \
  -o ./generated-client

Java

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g java \
  -o ./generated-client

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g csharp \
  -o ./generated-client

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g go \
  -o ./generated-client

Rust

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g rust \
  -o ./generated-client

When to Regenerate

Regenerate SDKs When:

Update data models - Changes to your TypeScript interfaces or Python models
Modify ingestion pipelines - Adding/removing fields or changing validation rules
Update consumption APIs - Changing query parameters or response schemas
Add new endpoints - New ingestion or consumption APIs
Change API configuration - Modifying authentication, rate limiting, etc.

Advanced Configuration

Custom Generator Options

You can customize the generated SDK with additional options:

openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g typescript-fetch \
  -o ./generated-client \
  --additional-properties=supportsES6=true,npmName=@myorg/moose-client,npmVersion=1.0.0

Multiple SDKs

Generate SDKs for multiple languages in one project:

# TypeScript for frontend
openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g typescript-fetch \
  -o ./frontend/generated-client
 
# Python for backend services
openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g python \
  -o ./backend/generated-client
 
# Go for microservices
openapi-generator-cli generate \
  -i .moose/openapi.yaml \
  -g go \
  -o ./services/generated-client

CI/CD Integration

Automate SDK generation in your CI/CD pipeline:

.github/workflows/generate-sdk.yml

name: Generate SDK
on:
  push:
    branches: [main]
    paths: ['app/**', 'moose.config.toml']
 
jobs:
  generate-sdk:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g @openapitools/openapi-generator-cli
      - run: moose dev &
      - run: sleep 10  # Wait for server to start
      - run: openapi-generator-cli generate -i .moose/openapi.yaml -g typescript-fetch -o ./generated-client
      - run: git add generated-client
      - run: git commit -m "Update generated SDK" || echo "No changes"
      - run: git push

Troubleshooting

Common Issues

SDK Generation Issues

Server not running: Ensure moose dev is running before generating SDKs
Outdated spec: Regenerate the OpenAPI spec by restarting the dev server
Type conflicts: Clear generated client directory before regenerating
Network errors: Check that the Moose server is accessible at the configured URL

Validation

Verify your OpenAPI spec is valid:

# Validate the OpenAPI spec
openapi-generator-cli validate -i .moose/openapi.yaml
 
# View the generated spec
cat .moose/openapi.yaml

Securing API Endpoints

Moose Migrate