@forinda/kickjs-swagger 2.0.1 → 2.2.0

package/README.md

@@ -31,11 +31,15 @@ bootstrap({
     new SwaggerAdapter({
       info: { title: 'My API', version: '1.0.0' },
       bearerAuth: true,
+      disableInProd: true, // skip mounting docs when NODE_ENV=production
     }),
   ],
 })
 ```
 
+Set `disableInProd: true` to skip mounting docs, the spec, and assets when
+`NODE_ENV === 'production'`.
+
 ### Custom Schema Parser (Joi)
 
 ```typescript

package/dist/index.d.mts

@@ -0,0 +1,187 @@
+
+import { AdapterContext, AppAdapter } from "@forinda/kickjs";
+
+//#region src/schema-parser.d.ts
+/**
+ * Interface for converting validation library schemas to JSON Schema.
+ *
+ * KickJS ships with a Zod parser by default. To use a different validation
+ * library (Yup, Joi, Valibot, ArkType, etc.), implement this interface and
+ * pass it to the SwaggerAdapter.
+ *
+ * @example
+ * ```ts
+ * import Joi from 'joi'
+ * import joiToJson from 'joi-to-json'
+ *
+ * const joiParser: SchemaParser = {
+ *   name: 'joi',
+ *   supports: (schema) => Joi.isSchema(schema),
+ *   toJsonSchema: (schema) => joiToJson(schema),
+ * }
+ *
+ * new SwaggerAdapter({ schemaParser: joiParser })
+ * ```
+ */
+interface SchemaParser {
+  /** Human-readable name for logging/debugging */
+  readonly name: string;
+  /**
+   * Return true if this parser can handle the given schema object.
+   * Called before `toJsonSchema` to allow graceful fallback.
+   */
+  supports(schema: unknown): boolean;
+  /**
+   * Convert a validation schema to a JSON Schema object.
+   * Should return a plain object conforming to JSON Schema draft-07 or later.
+   * Must not include the top-level `$schema` key — the builder adds it.
+   */
+  toJsonSchema(schema: unknown): Record<string, unknown>;
+}
+/**
+ * Default schema parser for Zod v4+.
+ * Uses Zod's built-in `.toJSONSchema()` instance method.
+ */
+declare const zodSchemaParser: SchemaParser;
+//#endregion
+//#region src/decorators.d.ts
+interface ApiOperationOptions {
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  deprecated?: boolean;
+}
+interface ApiResponseOptions {
+  status: number;
+  description?: string;
+  schema?: any;
+  /** Schema name in components/schemas (e.g., 'UserResponse', 'ErrorBody'). Auto-generated from handler name if omitted. */
+  name?: string;
+}
+/** Attach operation metadata to a route handler */
+declare function ApiOperation(options: ApiOperationOptions): MethodDecorator;
+/** Document a response status. Can be stacked multiple times. */
+declare function ApiResponse(options: ApiResponseOptions): MethodDecorator;
+/** Apply OpenAPI tags at class or method level */
+declare function ApiTags(...tags: string[]): ClassDecorator & MethodDecorator;
+/** Mark endpoint as requiring Bearer token auth */
+declare function ApiBearerAuth(name?: string): ClassDecorator & MethodDecorator;
+/** Exclude a controller or method from the OpenAPI spec */
+declare function ApiExclude(): ClassDecorator & MethodDecorator;
+//#endregion
+//#region src/openapi-builder.d.ts
+interface OpenAPIInfo {
+  title: string;
+  version: string;
+  description?: string;
+}
+interface SwaggerOptions {
+  info?: Partial<OpenAPIInfo>;
+  servers?: {
+    url: string;
+    description?: string;
+  }[];
+  bearerAuth?: boolean;
+  /**
+   * Pluggable schema parser for converting validation schemas to JSON Schema.
+   * Defaults to `zodSchemaParser` which handles Zod v4+ schemas.
+   *
+   * Override this to use Yup, Joi, Valibot, ArkType, or any other library.
+   *
+   * @example
+   * ```ts
+   * new SwaggerAdapter({
+   *   schemaParser: myYupParser,
+   * })
+   * ```
+   */
+  schemaParser?: SchemaParser;
+}
+/** Register a controller for OpenAPI introspection (called by Application during route mounting) */
+declare function registerControllerForDocs(controllerClass: any, mountPath: string): void;
+/** Clear all registered routes (for HMR) */
+declare function clearRegisteredRoutes(): void;
+/** Build a full OpenAPI 3.0.3 spec from registered controllers and their decorators */
+declare function buildOpenAPISpec(options?: SwaggerOptions): any;
+//#endregion
+//#region src/swagger.adapter.d.ts
+interface SwaggerAdapterOptions extends SwaggerOptions {
+  /** Path to serve Swagger UI (default: '/docs') */
+  docsPath?: string;
+  /** Path to serve ReDoc (default: '/redoc') */
+  redocPath?: string;
+  /** Path to serve the raw JSON spec (default: '/openapi.json') */
+  specPath?: string;
+  /** Other adapters to discover (e.g., WsAdapter for WebSocket server URLs) */
+  adapters?: any[];
+  /**
+   * When true, the adapter is a no-op while `NODE_ENV === 'production'` —
+   * docs, spec, and assets are not mounted. Useful for keeping API docs
+   * out of production builds without conditionally constructing the adapter.
+   */
+  disableInProd?: boolean;
+}
+/**
+ * Swagger adapter — auto-generates OpenAPI spec from decorators and serves docs.
+ *
+ * Assets are served locally from `swagger-ui-dist` (npm dependency) —
+ * no CDN required, works fully offline.
+ *
+ * @example
+ * ```ts
+ * bootstrap({
+ *   modules,
+ *   adapters: [
+ *     new SwaggerAdapter({
+ *       info: { title: 'My API', version: '1.0.0' },
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * Endpoints:
+ *   GET /docs         — Swagger UI (local assets, no CDN)
+ *   GET /redoc        — ReDoc (CDN — no local package available)
+ *   GET /openapi.json — Raw OpenAPI 3.0.3 spec
+ */
+declare class SwaggerAdapter implements AppAdapter {
+  private readonly options;
+  name: string;
+  constructor(options?: SwaggerAdapterOptions);
+  /** Whether the adapter should skip mounting in the current environment */
+  private get disabled();
+  /** Auto-detect server URLs from the running HTTP server and peer adapters */
+  afterStart({
+    server
+  }: AdapterContext): void;
+  /** Collect controller metadata as routes are mounted */
+  onRouteMount(controllerClass: any, mountPath: string): void;
+  beforeMount({
+    app
+  }: AdapterContext): void;
+}
+//#endregion
+//#region src/ui.d.ts
+/**
+ * Generate Swagger UI HTML using local assets from swagger-ui-dist.
+ *
+ * Assets are served from `/_swagger-assets/` by the adapter's Express
+ * static middleware. Falls back to CDN if the local path is not provided.
+ * This ensures Swagger UI works fully offline in development.
+ *
+ * @param specUrl - Path to the OpenAPI JSON spec (e.g., '/openapi.json')
+ * @param title - Page title
+ * @param assetsPath - Base path for local swagger-ui-dist assets (e.g., '/_swagger-assets')
+ */
+declare function swaggerUIHtml(specUrl: string, title?: string, assetsPath?: string): string;
+/**
+ * Generate ReDoc HTML.
+ *
+ * ReDoc doesn't publish a standalone npm package suitable for local serving,
+ * so it still loads from CDN. If offline support for ReDoc is needed,
+ * vendor the standalone bundle into the package's public/ directory.
+ */
+declare function redocHtml(specUrl: string, title?: string): string;
+//#endregion
+export { ApiBearerAuth, ApiExclude, ApiOperation, type ApiOperationOptions, ApiResponse, type ApiResponseOptions, ApiTags, type OpenAPIInfo, type SchemaParser, SwaggerAdapter, type SwaggerAdapterOptions, type SwaggerOptions, buildOpenAPISpec, clearRegisteredRoutes, redocHtml, registerControllerForDocs, swaggerUIHtml, zodSchemaParser };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/schema-parser.ts","../src/decorators.ts","../src/openapi-builder.ts","../src/swagger.adapter.ts","../src/ui.ts"],"mappings":";;;;;;;AAqBA;;;;;;;;;;;;AAsBA;;;;;;UAtBiB,YAAA;;WAEN,IAAA;ECXyB;;;;EDiBlC,QAAA,CAAS,MAAA;ECdT;;;;AAIF;EDiBE,YAAA,CAAa,MAAA,YAAkB,MAAA;AAAA;;;;;cAOpB,eAAA,EAAiB,YAAA;;;UC/Bb,mBAAA;EACf,OAAA;EACA,WAAA;EACA,WAAA;EACA,UAAA;AAAA;AAAA,UAGe,kBAAA;EACf,MAAA;EACA,WAAA;EACA,MAAA;EDqB4B;ECnB5B,IAAA;AAAA;;iBAIc,YAAA,CAAa,OAAA,EAAS,mBAAA,GAAsB,eAAA;AAhB5D;AAAA,iBAuBgB,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,eAAA;;iBAY1C,OAAA,CAAA,GAAW,IAAA,aAAiB,cAAA,GAAiB,eAAA;;iBAW7C,aAAA,CAAc,IAAA,YAAsB,cAAA,GAAiB,eAAA;;iBAWrD,UAAA,CAAA,GAAc,cAAA,GAAiB,eAAA;;;UCxD9B,WAAA;EACf,KAAA;EACA,OAAA;EACA,WAAA;AAAA;AAAA,UAGe,cAAA;EACf,IAAA,GAAO,OAAA,CAAQ,WAAA;EACf,OAAA;IAAY,GAAA;IAAa,WAAA;EAAA;EACzB,UAAA;EFcqC;;AAOvC;;;;;;;;AC/BA;;;ECwBE,YAAA,GAAe,YAAA;AAAA;;iBAWD,yBAAA,CAA0B,eAAA,OAAsB,SAAA;;iBAKhD,qBAAA,CAAA;;iBAKA,gBAAA,CAAiB,OAAA,GAAS,cAAA;;;UClCzB,qBAAA,SAA8B,cAAA;EHF9B;EGIf,QAAA;;EAEA,SAAA;EHJS;EGMT,QAAA;EHAS;EGET,QAAA;EHKa;;;;AAOf;EGNE,aAAA;AAAA;;;;;;AFzBF;;;;;;;;;;AAOA;;;;;;;;cE4Ca,cAAA,YAA0B,UAAA;EAAA,iBAGR,OAAA;EAF7B,IAAA;cAE6B,OAAA,GAAS,qBAAA;;cAG1B,QAAA,CAAA;EFzCwB;EE8CpC,UAAA,CAAA;IAAa;EAAA,GAAU,cAAA;EF9CmC;EE0E1D,YAAA,CAAa,eAAA,OAAsB,SAAA;EAKnC,WAAA,CAAA;IAAc;EAAA,GAAO,cAAA;AAAA;;;;;;AHtFvB;;;;;;;;iBIAgB,aAAA,CAAc,OAAA,UAAiB,KAAA,WAAoB,UAAA;;;;AJsBnE;;;;iBI0BgB,SAAA,CAAU,OAAA,UAAiB,KAAA"}