@richie-rpc/openapi

OpenAPI 3.1 specification generator for Richie RPC contracts.

Installation

bun add @richie-rpc/openapi @richie-rpc/core zod@^4

Usage

Generate OpenAPI Spec

import { generateOpenAPISpec } from '@richie-rpc/openapi';
import { contract } from './contract';

const spec = generateOpenAPISpec(contract, {
  info: {
    title: 'My API',
    version: '1.0.0',
    description: 'API description',
    contact: {
      name: 'API Support',
      email: '[email protected]'
    }
  },
  servers: [
    {
      url: 'https://api.example.com',
      description: 'Production server'
    },
    {
      url: 'http://localhost:3000',
      description: 'Development server'
    }
  ]
});

Generate OpenAPI Spec with basePath

If your API is served under a path prefix, use the basePath option to prefix all paths in the spec:

const spec = generateOpenAPISpec(contract, {
  info: {
    title: 'My API',
    version: '1.0.0'
  },
  basePath: '/api'  // All paths will be prefixed with /api
});

// If contract defines /users, the OpenAPI spec will show /api/users

Serve OpenAPI Spec

import { createOpenAPIResponse } from '@richie-rpc/openapi';

Bun.serve({
  fetch(request) {
    const url = new URL(request.url);
    
    if (url.pathname === '/openapi.json') {
      return createOpenAPIResponse(contract, {
        info: { title: 'My API', version: '1.0.0' }
      });
    }
    
    // ... other routes
  }
});

Serve API Documentation UI

The package includes support for Scalar API documentation UI:

import { createDocsResponse } from '@richie-rpc/openapi';

Bun.serve({
  fetch(request) {
    const url = new URL(request.url);
    
    if (url.pathname === '/docs') {
      return createDocsResponse('/openapi.json', {
        title: 'My API Documentation',
        layout: 'modern'
      });
    }
    
    // ... other routes
  }
});

Features

• ✅ OpenAPI 3.1 specification generation
• ✅ Automatic Zod to JSON Schema conversion using Zod v4's built-in z.toJSONSchema()
• ✅ No external JSON Schema conversion dependencies
• ✅ Path parameters, query parameters, request bodies
• ✅ Multiple response types per endpoint
• ✅ BasePath support for prefixing all paths
• ✅ Server and info metadata support
• ✅ Scalar API documentation UI integration
• ✅ Modern, interactive documentation

API Reference

generateOpenAPISpec(contract, options)

Generates an OpenAPI 3.1 specification from a contract.

Parameters:

• contract: The Richie RPC contract
• options.info: OpenAPI info object (required)
  • title: API title
  • version: API version
  • description: API description (optional)
  • contact: Contact information (optional)
  • license: License information (optional)
• options.servers: Array of server objects (optional)
• options.basePath: Path prefix for all endpoints (optional, e.g., /api)

Returns: OpenAPI specification object

createOpenAPIResponse(contract, options)

Creates a Response object with the OpenAPI spec as JSON.

createDocsResponse(openAPIUrl, options)

Creates a Response object with HTML for Scalar API documentation.

Parameters:

• openAPIUrl: Path to OpenAPI spec JSON (default: /openapi.json)
• options.title: Documentation title
• options.layout: UI layout ('modern' or 'classic')
• options.showToolbar: Show toolbar ('always', 'never', or 'auto')
• options.hideClientButton: Hide client button (boolean)

OpenAPI Spec Structure

The generated spec includes:

• Paths: All endpoints with their operations
• Parameters: Path and query parameters with schemas
• Request Bodies: JSON schemas for request bodies
• Responses: Status codes mapped to response schemas
• Schemas: Automatically generated from Zod schemas

Example Output

{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users/{id}": {
      "get": {
        "operationId": "getUser",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { ... }
              }
            }
          }
        }
      }
    }
  }
}

Links

• npm: https://www.npmjs.com/package/@richie-rpc/openapi
• Repository: https://github.com/ricsam/richie-rpc

License

MIT