ApiDocumentFactory

Package: @opra/common

ApiDocumentFactory builds and validates an ApiDocument from a plain init object, a URL, or an OpraSchema.ApiDocument plain schema. It is the only supported way to construct an ApiDocument at runtime — you do not call new ApiDocument() directly.

---

Usage

import { ApiDocumentFactory } from '@opra/common';

const document = await ApiDocumentFactory.createDocument({
  info: { title: 'My API', version: '1.0.0' },
  types: [Customer, Address],
  api: {
    transport: 'http',
    url: 'https://api.example.com',
    controllers: [CustomerController],
  },
});

---

ApiDocumentFactory.createDocument(schemaOrUrl, options?)

The single static entry point. Accepts an init object, a URL string to fetch the schema from, or a raw OpraSchema.ApiDocument plain object. Always returns a Promise<ApiDocument>.

static async createDocument(
  schemaOrUrl: string | ApiDocumentFactory.InitArguments | OpraSchema.ApiDocument,
  options?: {
    maxErrors?: number;
    showErrorDetails?: boolean;
  },
): Promise<ApiDocument>

If validation finds errors, the returned promise rejects with an OpraDocumentError containing all collected issues. Pass showErrorDetails: true to embed the issue list in the error message.

Loading from a URL

Pass a URL string to fetch the schema over HTTP. The factory issues a GET request, parses the JSON response, and initialises the document exactly as if you had passed the object directly.

const document = await ApiDocumentFactory.createDocument(
  'https://api.example.com/schema.json',
);

---

ApiDocumentFactory.InitArguments

The shape of the init object passed to createDocument.

Field	Type	Description
spec	string	OPRA spec version string. Defaults to the current version if omitted.
url	string | undefined	Base URL of the document. Set automatically when loading from a URL string.
info	OpraSchema.ApiDocument.Info | undefined	Document metadata — title, version, description, license, contact.
references	Record<string, ReferenceThunk> | undefined	Namespaced references to other ApiDocument instances or schemas. Values may be async thunks.
types	DataTypeFactory.DataTypeSources | undefined	Data types to register — TypeScript classes decorated with @ComplexType(), @SimpleType(), EnumType(...) results, or plain schema objects.
api	HttpApiFactory.InitArguments | MQApiFactory.InitArguments | WSApiFactory.InitArguments | undefined	API transport configuration. The transport field selects the kind ('http', 'mq', or 'ws').

Built-in types

Every document automatically receives the full set of OPRA built-in types (string, integer, number, boolean, date, datetime, uuid, base64, …). You do not need to register them manually.

References

references lets you import types from another document under a namespace:

const document = await ApiDocumentFactory.createDocument({
  references: {
    shared: () => fetch('/shared-schema.json').then(r => r.json()),
    auth: existingAuthDocument,
  },
  types: [Customer],
  api: { transport: 'http', controllers: [CustomerController] },
});

Each reference value is a ThunkAsync<ReferenceSource> — it can be a plain object, an ApiDocument instance, another InitArguments object, or an async function that resolves to any of those.

---

Error handling

try {
  const document = await ApiDocumentFactory.createDocument(init, {
    showErrorDetails: true,
  });
} catch (e) {
  // e is an OpraDocumentError with e.details[] listing each issue
  console.error(e.message);
}

Set maxErrors to stop collection after a given number of issues (useful for large schemas where you only want the first few problems).

---

→ ApiDocument · ComplexType