rxdb-openapi

OpenAPI 3.1.0 plugin for RxDB Server — auto-generates a /openapi.json route from your REST endpoint collection schemas.

RxDB Server's REST endpoint exposes 5 fixed routes per collection but ships no OpenAPI spec. This package generates one automatically from your collection schemas and serves it as a middleware.

Install

npm install rxdb-openapi

Quick start

import express from 'express';
import { createRxServer } from 'rxdb-server/plugins/server';
import { RxServerAdapterExpress } from 'rxdb-server/plugins/adapter-express';
import { createOpenApiMiddleware, endpointFromCollection } from 'rxdb-openapi';

const app = express();

const myServer = await createRxServer({
  database: myRxDatabase,
  adapter: RxServerAdapterExpress,
  port: 3000
});

const ep = await myServer.addRestEndpoint({
  name: 'users',
  collection: usersCollection
});

// Mount before server.start()
app.use(createOpenApiMiddleware({
  title: 'My App API',
  serverUrl: 'http://localhost:3000',
  endpoints: [
    endpointFromCollection('users', usersCollection)
  ]
}));

await myServer.start();
// GET http://localhost:3000/openapi.json  →  OpenAPI 3.1.0 JSON

API

generateOpenApiSpec(options): object

Pure function — returns an OpenAPI 3.1.0 spec object. No side effects. Useful when you want to write the spec to disk or serve it yourself.

import { generateOpenApiSpec } from 'rxdb-openapi';

const spec = generateOpenApiSpec({
  title: 'My App',
  apiVersion: '1.0.0',
  serverUrl: 'http://localhost:3000',
  endpoints: [
    { name: 'users', schemaVersion: 0, jsonSchema: usersCollection.schema.jsonSchema }
  ]
});

generateOpenApiJson(options, pretty?): string

Same as above but returns a JSON string directly. pretty defaults to true.

import { generateOpenApiJson } from 'rxdb-openapi';
import { writeFileSync } from 'node:fs';

writeFileSync('openapi.json', generateOpenApiJson({ endpoints: [...] }));

createOpenApiMiddleware(options): RequestHandler

Returns an Express-compatible middleware that responds to GET /openapi.json.

app.use(createOpenApiMiddleware({ endpoints: [...] }));

endpointFromCollection(name, collection): EndpointConfig

Helper that extracts an EndpointConfig from a live RxCollection instance.

const config = endpointFromCollection('users', usersCollection);
// { name: 'users', schemaVersion: 0, jsonSchema: { ... } }

Generated routes per collection

Each { name, schemaVersion } pair produces 5 paths in the spec:

| Method | Path | Description | |--------|------|-------------| | POST | /{name}/{version}/query | Mango query (selector, sort, limit, skip) | | GET | /{name}/{version}/query/observe | SSE stream of query results | | POST | /{name}/{version}/get | Fetch documents by primary key | | POST | /{name}/{version}/set | Upsert documents | | POST | /{name}/{version}/delete | Delete by primary key |

RxDB internal fields (_deleted, _rev, _meta, _attachments) are merged into each document schema automatically.

Options

interface OpenApiOptions {
  title?: string;      // Default: "RxDB Server API"
  apiVersion?: string; // Default: "1.0.0"
  serverUrl?: string;  // e.g. "http://localhost:3000" — adds servers[] to spec
  endpoints: EndpointConfig[];
}

interface EndpointConfig {
  name: string;
  schemaVersion?: number;              // Default: 0
  jsonSchema: Record<string, unknown>; // RxDB collection JSON schema
}

Non-JavaScript clients

The generated OpenAPI spec can be used with any language. Example: generate a Python client with openapi-python-client:

openapi-python-client generate --url http://localhost:3000/openapi.json

Or use it from NAOqi Python on Pepper without any client generation — just plain urllib.request against the documented routes.

License

MIT