@ortha/api-docs

Fastify plugin for API documentation — generates OpenAPI/Swagger specs from route schemas and serves an interactive documentation UI via Scalar.

Installation

Internal monorepo dependency — import directly:

import { apiDocsPlugin } from '@ortha/api-docs';
import type { DocsConfig } from '@ortha/api-docs';

Usage

Registering the plugin

import { bootstrap } from '@ortha/server-platform-bootstrap';
import { apiDocsPlugin } from '@ortha/api-docs';

await bootstrap({
    config: bootstrapConfig,
    plugins: [
        // Register BEFORE domain plugins to capture all routes
        apiDocsPlugin({
            title: 'Ortha API',
            version: '1.0.0',
            description: 'Ortha CMS API documentation'
        })
        // ...domain plugins
    ]
});

Important: The docs plugin must be registered before domain plugins so it can capture all route schemas for the OpenAPI spec.

Accessing the documentation

Once the server is running, the interactive API documentation is available at:

http://localhost:4000/docs

API Reference

| Export | Kind | Description | | ----------------- | ------- | ---------------------------------------------- | | apiDocsPlugin() | factory | Fastify plugin — registers Swagger + Scalar UI | | DocsConfig | type | Configuration for docs (title, version, etc.) |

DocsConfig

| Property | Type | Description | | ------------- | -------- | ----------------------- | | title | string | API documentation title | | version | string | API version string | | description | string | API description text |

Internal Structure

src/lib/
├── types/index.ts              # DocsConfig type
└── apiDocsPlugin/index.ts      # Fastify plugin factory (fp wrapper)

Dependencies

• @fastify/swagger — OpenAPI spec generation from route schemas
• @scalar/fastify-api-reference — Interactive API documentation UI at /docs

Key Patterns

• The plugin uses fastify-plugin (fp) wrapper to share the Swagger decorator across the Fastify instance.
• Route schemas (JSON Schema) defined in domain plugins are automatically picked up for the OpenAPI spec.
• Scalar provides a modern, interactive UI alternative to Swagger UI.

Building

nx build api-docs