Skip to main content

Quik Framework :: OpenAPI

Generates OpenAPI documentation for the framework. The module sets up an API docs provider and registers entity and route parsers used during OpenAPI generation.

Installation​

npm install @quik/openapi

Usage​

Generate the OpenAPI document:

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

const spec = getOpenApiObject();

getOpenApiObject() returns a cached document and will auto-populate the cache the first time it is called.

Register custom parser hooks:

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

OpenAPIHooks.addTagsParser((tags) => tags);

API Highlights​

  • getOpenApiObject() returns the cached OpenAPI document.
  • cacheOpenAPIObject() refreshes the cached document.
  • OpenAPIHooks lets you extend components, paths, tags, security, webhooks.
  • getApiDocs().getApiJson({ mode: 'swagger-ui' }) returns a Swagger UI compatible projection that omits unsupported security schemes such as custom WebAuthn HTTP schemes.

Customization Points​

Parser hooks allow you to inject custom data into the OpenAPI document:

  • Components hooks return { name, definition } to merge into components.
  • Paths hooks return additional paths entries.
  • Tags hooks return additional tags entries.
  • Security and webhooks hooks return their respective objects.

When merging, later hooks can override values from earlier hooks.

Extension Fields​

OpenAPI extension fields (x-...) are supported anywhere the spec allows custom properties. Include them in your hook return values to attach framework specific metadata.

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the openapi API section.