OpenAPI Integration
@opra/openapi generates standard OpenAPI 3.0 / 3.1 documents from an OPRA ApiDocument. Once you have an ApiDocument — the runtime representation of your OPRA HTTP service — this package converts it to a spec-compliant JSON object you can serve with Swagger UI, import into Postman, feed to API gateways, or use with any OpenAPI-aware tooling.
Installation
npm install @opra/openapi
@opra/common is a peer dependency; install it too if you haven't already.
How it works
OPRA's ApiDocument already contains everything needed: controllers, operations, typed request/response shapes, parameters, and the data type registry. @opra/openapi walks this structure and maps each piece to its OpenAPI equivalent:
| OPRA construct | OpenAPI equivalent |
|---|---|
HttpController | Path items (grouped by URL) |
HttpOperation | Operation object (get, post, … under each path) |
.QueryParam(), .PathParam(), .Header(), .Cookie() | parameters[] |
.RequestContent() | requestBody |
.Response() | responses |
ComplexType / MappedType / MixinType | components.schemas object |
EnumType | components.schemas {type:"string", enum:[...]} |
ArrayType | {type:"array", items:...} |
UnionType | {oneOf:[...]} |
SimpleType | Inlined primitive schema (string, integer, boolean, …) |
Named model types (ComplexType, EnumType, UnionType, ArrayType) are placed in components.schemas and referenced with $ref. Simple types are always inlined.
Quick example
import { ApiDocumentFactory, OpraSchema } from '@opra/common';
import { OpenApiDocumentFactory } from '@opra/openapi';
// Build (or obtain) your ApiDocument
const apiDocument = await ApiDocumentFactory.createDocument({ ... });
// Generate an OpenAPI 3.0 document
const openApiDoc = OpenApiDocumentFactory.generate(apiDocument);
// openApiDoc is a plain JSON-serialisable object — serve or write it
console.log(JSON.stringify(openApiDoc, null, 2));