@soapjs/soap-openapi

OpenAPI 3 documentation for SoapJS HTTP apps: route metadata collectors, JSON/YAML endpoints, and Swagger UI through DocumentationPlugin.

Install

npm install @soapjs/soap-openapi @soapjs/soap @soapjs/soap-express express

Usage

import { bootstrap } from '@soapjs/soap-express';
import { DocumentationPlugin } from '@soapjs/soap-openapi';

await bootstrap({
  controllers: [MyController],
  plugins: [
    {
      plugin: new DocumentationPlugin(),
      options: {
        info: { title: 'My API', version: '1.0.0' },
        servers: [{ url: 'http://localhost:3000' }],
        openApiPath: '/openapi.json',
        interactivePath: '/docs',
        securitySchemes: {
          bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
        },
      },
    },
  ],
});

The plugin reads RouteAdditionalOptions.apiDoc from the SoapJS route registry. Pair it with @soapjs/soap-contract-zod so bodyContract(), queryContract(), and paramsContract() metadata appears in the generated spec automatically.

Endpoints

By default the plugin mounts:

• /openapi.json - OpenAPI 3.0.3 JSON
• /api-docs.json - OpenAPI 3.0.3 JSON
• /api-docs.yaml - OpenAPI 3.0.3 YAML
• /docs - Swagger UI
• /api-docs/stats - documentation coverage stats

All paths can be overridden with openApiPath, jsonPath, yamlPath, interactivePath, and statsPath.

Options

• info - required OpenAPI info object.
• servers, tags, externalDocs, components - copied into the OpenAPI document.
• security - global OpenAPI security requirements.
• securitySchemes - shortcut for components.securitySchemes.
• includeUndocumentedRoutes - includes routes without apiDoc with a default response; defaults to true.
• defaultResponse - default response used for undocumented routes.

Peer dependencies

• @soapjs/soap >= 0.14.0 (DecoratorRegistry in @soapjs/soap/http)
• express >= 4 (your HTTP stack, e.g. @soapjs/soap-express)