Recipes

Add extra tags to the generated document

import { OpenAPIHooks } from '@quik/openapi';

OpenAPIHooks.addTagsParser((tags) => [
  ...tags,
  { name: 'Internal', description: 'Internal-only endpoints.' }
]);

Add components (schemas, security schemes, etc.)

import { OpenAPIHooks } from '@quik/openapi';

OpenAPIHooks.addComponentsParser((components) => ({
  name: 'schemas',
  definition: {
    HealthStatus: {
      type: 'object',
      properties: { ok: { type: 'boolean' } }
    }
  }
}));

Each components hook returns { name, definition }; later hooks merge into the same components.<name> object, overriding keys from earlier hooks with the same name.

Add custom paths or webhooks

import { OpenAPIHooks } from '@quik/openapi';

OpenAPIHooks.addPathsParser((paths) => ({
  ...paths,
  '/health': { get: { summary: 'Health check', responses: { '200': { description: 'OK' } } } }
}));

OpenAPIHooks.addWebhooksParser((webhooks) => webhooks);

Force-refresh the cached document

By default, getOpenApiObject() builds the document once and caches it; it is also rebuilt once automatically in the onBeforeBoot lifecycle hook. Call cacheOpenAPIObject() manually after registering new hooks or routes at runtime (e.g. in a test, or after dynamic route registration) so subsequent getOpenApiObject() calls reflect the change.

import { cacheOpenAPIObject, getOpenApiObject } from '@quik/openapi';

OpenAPIHooks.addTagsParser((tags) => [ ...tags, { name: 'Reports' } ]);
cacheOpenAPIObject();

const spec = getOpenApiObject();

Swagger UI compatible projection

Swagger UI does not support every OpenAPI 3.1 security scheme (e.g. custom WebAuthn HTTP schemes registered by @quik/passport). Use the swagger-ui mode when serving the document to Swagger UI:

import { getApiDocs } from '@quik/core';

const swaggerDoc = getApiDocs().getApiJson({ mode: 'swagger-ui' });