@richie-rpc/openapi

OpenAPI 3.1 specification generator for Richie RPC contracts.

Installation

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

Usage

$3

`typescript
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: 'support@example.com',
},
},
servers: [
{
url: 'https://api.example.com',
description: 'Production server',
},
{
url: 'http://localhost:3000',
description: 'Development server',
},
],
});
`

$3

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

`typescript
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
`

$3

`typescript
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
},
});
`

$3

The package includes support for Scalar API documentation UI:

`typescript
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

$3

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

$3

Creates a Response object with the OpenAPI spec as JSON.

$3

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

`json
{
"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