@fluojs/openapi 1.0.0-beta.1

package/dist/decorators.js

@@ -0,0 +1,400 @@
+import { metadataSymbol } from '@fluojs/core/internal';
+
+/**
+ * User-facing operation metadata accepted by `@ApiOperation(...)`.
+ */
+
+/**
+ * User-facing response metadata accepted by `@ApiResponse(...)`.
+ */
+
+/**
+ * User-facing parameter metadata accepted by `@ApiParam(...)`, `@ApiQuery(...)`, `@ApiHeader(...)`, and `@ApiCookie(...)`.
+ */
+
+/**
+ * User-facing request-body metadata accepted by `@ApiBody(...)`.
+ */
+
+/**
+ * Normalized operation metadata stored on controller methods.
+ */
+
+/**
+ * Stored OpenAPI security requirement metadata for a single operation.
+ */
+
+/**
+ * Normalized response metadata stored on controller methods.
+ */
+
+/**
+ * Normalized parameter metadata stored on controller methods.
+ */
+
+/**
+ * Normalized request-body metadata stored on controller methods.
+ */
+
+/**
+ * Aggregated OpenAPI metadata snapshot for a controller method.
+ */
+
+const openApiControllerTagsKey = Symbol.for('fluo.openapi.controller-tags');
+const openApiMethodOperationKey = Symbol.for('fluo.openapi.method-operation');
+const openApiMethodResponsesKey = Symbol.for('fluo.openapi.method-responses');
+const openApiMethodParametersKey = Symbol.for('fluo.openapi.method-parameters');
+const openApiMethodRequestBodyKey = Symbol.for('fluo.openapi.method-request-body');
+const openApiMethodSecurityKey = Symbol.for('fluo.openapi.method-security');
+const openApiMethodSecurityRequirementsKey = Symbol.for('fluo.openapi.method-security-requirements');
+const openApiMethodExcludeEndpointKey = Symbol.for('fluo.openapi.method-exclude-endpoint');
+function getMetadataBag(target) {
+  void metadataSymbol;
+  return target[metadataSymbol];
+}
+function cloneUnknown(value) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(entry => cloneUnknown(entry));
+  }
+  if (typeof value !== 'object') {
+    return value;
+  }
+  const clone = {};
+  for (const key of Reflect.ownKeys(value)) {
+    clone[key] = cloneUnknown(value[key]);
+  }
+  return clone;
+}
+function cloneApiOperationMetadata(operation) {
+  if (!operation) {
+    return undefined;
+  }
+  return {
+    deprecated: operation.deprecated,
+    description: operation.description,
+    summary: operation.summary
+  };
+}
+function cloneApiSecurityRequirementMetadata(requirement) {
+  const clone = {};
+  for (const [scheme, scopes] of Object.entries(requirement)) {
+    clone[scheme] = [...scopes];
+  }
+  return clone;
+}
+function cloneApiResponseMetadata(response) {
+  return {
+    description: response.description,
+    schema: cloneUnknown(response.schema),
+    status: response.status,
+    type: response.type
+  };
+}
+function cloneApiParameterMetadata(parameter) {
+  return {
+    description: parameter.description,
+    in: parameter.in,
+    name: parameter.name,
+    required: parameter.required,
+    schema: cloneUnknown(parameter.schema)
+  };
+}
+function cloneApiBodyMetadata(requestBody) {
+  return {
+    ...(requestBody.content !== undefined ? {
+      content: cloneUnknown(requestBody.content)
+    } : {}),
+    ...(requestBody.description !== undefined ? {
+      description: requestBody.description
+    } : {}),
+    ...(requestBody.required !== undefined ? {
+      required: requestBody.required
+    } : {}),
+    ...(requestBody.schema !== undefined ? {
+      schema: cloneUnknown(requestBody.schema)
+    } : {})
+  };
+}
+
+/**
+ * Read tags registered via `@ApiTag` on a controller class.
+ *
+ * @param target Controller class token.
+ * @returns A defensive copy of registered tags, or `undefined` when no tags are present.
+ */
+export function getControllerTags(target) {
+  const bag = getMetadataBag(target);
+  const tags = bag?.[openApiControllerTagsKey];
+  return tags ? [...tags] : undefined;
+}
+
+/**
+ * Read OpenAPI metadata registered for a controller method.
+ *
+ * @param target Controller class token.
+ * @param propertyKey Controller method key to inspect.
+ * @returns A defensive metadata snapshot, or `undefined` when the method has no OpenAPI metadata.
+ */
+export function getMethodApiMetadata(target, propertyKey) {
+  const bag = getMetadataBag(target);
+  const operationMap = bag?.[openApiMethodOperationKey];
+  const responsesMap = bag?.[openApiMethodResponsesKey];
+  const parametersMap = bag?.[openApiMethodParametersKey];
+  const requestBodyMap = bag?.[openApiMethodRequestBodyKey];
+  const securityMap = bag?.[openApiMethodSecurityKey];
+  const securityRequirementsMap = bag?.[openApiMethodSecurityRequirementsKey];
+  const excludeEndpointMap = bag?.[openApiMethodExcludeEndpointKey];
+  const operation = operationMap?.get(propertyKey);
+  const responses = responsesMap?.get(propertyKey);
+  const parameters = parametersMap?.get(propertyKey);
+  const requestBody = requestBodyMap?.get(propertyKey);
+  const security = securityMap?.get(propertyKey);
+  const securityRequirements = securityRequirementsMap?.get(propertyKey);
+  const excludeEndpoint = excludeEndpointMap?.get(propertyKey);
+  if (!operation && !responses && !parameters && !requestBody && !security && !securityRequirements && !excludeEndpoint) {
+    return undefined;
+  }
+  return {
+    operation: cloneApiOperationMetadata(operation),
+    responses: (responses ?? []).map(response => cloneApiResponseMetadata(response)),
+    parameters: parameters?.map(parameter => cloneApiParameterMetadata(parameter)),
+    requestBody: requestBody ? cloneApiBodyMetadata(requestBody) : undefined,
+    security: security ? [...security] : undefined,
+    securityRequirements: securityRequirements?.map(requirement => cloneApiSecurityRequirementMetadata(requirement)),
+    excludeEndpoint
+  };
+}
+/**
+ * Attach an OpenAPI tag to a controller class.
+ *
+ * Multiple tags can be declared by stacking `@ApiTag(...)` decorators.
+ *
+ * @param tag Tag label appended to the controller-level tag list.
+ * @returns A class decorator that stores controller tag metadata.
+ */
+export function ApiTag(tag) {
+  return (_value, context) => {
+    const bag = context.metadata;
+    const existing = bag[openApiControllerTagsKey] ?? [];
+    bag[openApiControllerTagsKey] = [...existing, tag];
+  };
+}
+
+/**
+ * Describe a controller method's OpenAPI operation metadata.
+ *
+ * @param options Operation metadata such as summary, description, and deprecation flag.
+ * @returns A method decorator that stores operation metadata.
+ */
+export function ApiOperation(options) {
+  return (_value, context) => {
+    const bag = context.metadata;
+    let map = bag[openApiMethodOperationKey];
+    if (!map) {
+      map = new Map();
+      bag[openApiMethodOperationKey] = map;
+    }
+    map.set(context.name, {
+      deprecated: options.deprecated,
+      description: options.description,
+      summary: options.summary
+    });
+  };
+}
+
+/**
+ * Exclude a controller method from generated OpenAPI `paths`.
+ *
+ * @returns A method decorator that marks the endpoint as excluded.
+ */
+export function ApiExcludeEndpoint() {
+  return (_value, context) => {
+    const bag = context.metadata;
+    let map = bag[openApiMethodExcludeEndpointKey];
+    if (!map) {
+      map = new Map();
+      bag[openApiMethodExcludeEndpointKey] = map;
+    }
+    map.set(context.name, true);
+  };
+}
+
+/**
+ * Add a security requirement to a controller method in the generated OpenAPI document.
+ *
+ * @param name Security scheme name (for example `bearerAuth`, `oauth2`, `apiKey`).
+ * @param scopes Optional OAuth scopes associated with this security requirement.
+ * @returns A method decorator that appends security metadata.
+ */
+export function ApiSecurity(name, scopes = []) {
+  return (_value, context) => {
+    const bag = context.metadata;
+    let securityMap = bag[openApiMethodSecurityKey];
+    if (!securityMap) {
+      securityMap = new Map();
+      bag[openApiMethodSecurityKey] = securityMap;
+    }
+    const existingSecurityNames = securityMap.get(context.name) ?? [];
+    if (!existingSecurityNames.includes(name)) {
+      securityMap.set(context.name, [...existingSecurityNames, name]);
+    }
+    let requirementsMap = bag[openApiMethodSecurityRequirementsKey];
+    if (!requirementsMap) {
+      requirementsMap = new Map();
+      bag[openApiMethodSecurityRequirementsKey] = requirementsMap;
+    }
+    const existingRequirements = requirementsMap.get(context.name) ?? [];
+    requirementsMap.set(context.name, [...existingRequirements, {
+      [name]: [...scopes]
+    }]);
+  };
+}
+function registerMethodParameter(parameter) {
+  return (_value, context) => {
+    const bag = context.metadata;
+    let map = bag[openApiMethodParametersKey];
+    if (!map) {
+      map = new Map();
+      bag[openApiMethodParametersKey] = map;
+    }
+    const existing = map.get(context.name) ?? [];
+    map.set(context.name, [...existing, cloneApiParameterMetadata(parameter)]);
+  };
+}
+
+/**
+ * Declare a path parameter for a controller method.
+ *
+ * @param name Parameter name.
+ * @param options Optional parameter metadata such as description, required, and schema.
+ * @returns A method decorator that appends path-parameter metadata.
+ */
+export function ApiParam(name, options = {}) {
+  return registerMethodParameter({
+    description: options.description,
+    in: 'path',
+    name,
+    required: options.required ?? true,
+    schema: options.schema
+  });
+}
+
+/**
+ * Declare a query parameter for a controller method.
+ *
+ * @param name Parameter name.
+ * @param options Optional parameter metadata such as description, required, and schema.
+ * @returns A method decorator that appends query-parameter metadata.
+ */
+export function ApiQuery(name, options = {}) {
+  return registerMethodParameter({
+    description: options.description,
+    in: 'query',
+    name,
+    required: options.required,
+    schema: options.schema
+  });
+}
+
+/**
+ * Declare a header parameter for a controller method.
+ *
+ * @param name Parameter name.
+ * @param options Optional parameter metadata such as description, required, and schema.
+ * @returns A method decorator that appends header-parameter metadata.
+ */
+export function ApiHeader(name, options = {}) {
+  return registerMethodParameter({
+    description: options.description,
+    in: 'header',
+    name,
+    required: options.required,
+    schema: options.schema
+  });
+}
+
+/**
+ * Declare a cookie parameter for a controller method.
+ *
+ * @param name Parameter name.
+ * @param options Optional parameter metadata such as description, required, and schema.
+ * @returns A method decorator that appends cookie-parameter metadata.
+ */
+export function ApiCookie(name, options = {}) {
+  return registerMethodParameter({
+    description: options.description,
+    in: 'cookie',
+    name,
+    required: options.required,
+    schema: options.schema
+  });
+}
+
+/**
+ * Declare an explicit request body for a controller method.
+ *
+ * @param options Request-body metadata and schema/content declarations.
+ * @returns A method decorator that stores request-body metadata.
+ */
+export function ApiBody(options) {
+  return (_value, context) => {
+    const bag = context.metadata;
+    let map = bag[openApiMethodRequestBodyKey];
+    if (!map) {
+      map = new Map();
+      bag[openApiMethodRequestBodyKey] = map;
+    }
+    map.set(context.name, cloneApiBodyMetadata(options));
+  };
+}
+function normalizeApiResponseOptions(statusOrOptions, options) {
+  if (typeof statusOrOptions === 'number') {
+    return {
+      status: statusOrOptions,
+      ...options
+    };
+  }
+  return statusOrOptions;
+}
+
+/** Declare an expected HTTP response for a controller method. */
+
+/** Declare an expected HTTP response for a controller method. */
+
+/**
+ * Declare an expected HTTP response for a controller method.
+ *
+ * @param statusOrOptions Either a numeric status code or full response-options object.
+ * @param options Optional response metadata when the first argument is numeric status.
+ * @returns A method decorator that appends response metadata for the method.
+ */
+export function ApiResponse(statusOrOptions, options) {
+  const normalized = normalizeApiResponseOptions(statusOrOptions, options);
+  return (_value, context) => {
+    const bag = context.metadata;
+    let map = bag[openApiMethodResponsesKey];
+    if (!map) {
+      map = new Map();
+      bag[openApiMethodResponsesKey] = map;
+    }
+    const existing = map.get(context.name) ?? [];
+    map.set(context.name, [...existing, cloneApiResponseMetadata({
+      description: normalized.description,
+      schema: normalized.schema,
+      status: normalized.status,
+      type: normalized.type
+    })]);
+  };
+}
+
+/**
+ * Mark a controller method as requiring Bearer token authentication in the OpenAPI spec.
+ *
+ * @returns A method decorator equivalent to `ApiSecurity('bearerAuth')`.
+ */
+export function ApiBearerAuth() {
+  return ApiSecurity('bearerAuth');
+}

package/dist/handler-registry.d.ts

@@ -0,0 +1,20 @@
+import type { HandlerDescriptor } from '@fluojs/http';
+/**
+ * Mutable registry used to snapshot handler descriptors before document generation.
+ */
+export declare class OpenApiHandlerRegistry {
+    private descriptors;
+    /**
+     * Replace the current handler-descriptor snapshot.
+     *
+     * @param descriptors Handler descriptors to retain for later document generation.
+     */
+    setDescriptors(descriptors: readonly HandlerDescriptor[]): void;
+    /**
+     * Read the registered handler-descriptor snapshot.
+     *
+     * @returns A defensive copy of the current handler descriptors.
+     */
+    getDescriptors(): HandlerDescriptor[];
+}
+//# sourceMappingURL=handler-registry.d.ts.map

package/dist/handler-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-registry.d.ts","sourceRoot":"","sources":["../src/handler-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;GAEG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,WAAW,CAA2B;IAE9C;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI;IAI/D;;;;OAIG;IACH,cAAc,IAAI,iBAAiB,EAAE;CAGtC"}

package/dist/handler-registry.js

@@ -0,0 +1,24 @@
+/**
+ * Mutable registry used to snapshot handler descriptors before document generation.
+ */
+export class OpenApiHandlerRegistry {
+  descriptors = [];
+
+  /**
+   * Replace the current handler-descriptor snapshot.
+   *
+   * @param descriptors Handler descriptors to retain for later document generation.
+   */
+  setDescriptors(descriptors) {
+    this.descriptors = [...descriptors];
+  }
+
+  /**
+   * Read the registered handler-descriptor snapshot.
+   *
+   * @returns A defensive copy of the current handler descriptors.
+   */
+  getDescriptors() {
+    return [...this.descriptors];
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './decorators.js';
+export * from './handler-registry.js';
+export * from './openapi-module.js';
+export * from './schema-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './decorators.js';
+export * from './handler-registry.js';
+export * from './openapi-module.js';
+export * from './schema-builder.js';

package/dist/openapi-module.d.ts

@@ -0,0 +1,63 @@
+import { type HandlerDescriptor, type HandlerSource } from '@fluojs/http';
+import { type AsyncModuleOptions, type Constructor } from '@fluojs/core';
+import { type ModuleType } from '@fluojs/runtime';
+import { type DefaultErrorResponsesPolicy, type OpenApiDocument, type OpenApiSecuritySchemeObject } from './schema-builder.js';
+/**
+ * Public options for `OpenApiModule.forRoot(...)` and `OpenApiModule.forRootAsync(...)`.
+ *
+ * @remarks
+ * Keep README examples for full controller/module workflows. These options are
+ * intended to document the runtime hooks that shape the generated document.
+ */
+export interface OpenApiModuleOptions {
+    defaultErrorResponsesPolicy?: DefaultErrorResponsesPolicy;
+    title: string;
+    version: string;
+    ui?: boolean;
+    descriptors?: readonly HandlerDescriptor[];
+    sources?: readonly HandlerSource[];
+    securitySchemes?: Record<string, OpenApiSecuritySchemeObject>;
+    extraModels?: Constructor[];
+    documentTransform?: (document: OpenApiDocument) => OpenApiDocument;
+}
+/**
+ * Runtime module entrypoint for serving OpenAPI JSON and optional Swagger UI.
+ */
+export declare class OpenApiModule {
+    /**
+     * Registers OpenAPI providers using static options.
+     *
+     * @param options Static module options used to build and serve the OpenAPI document.
+     * @returns A runtime module type that can be imported in `@Module({ imports: [...] })`.
+     *
+     * @example
+     * ```ts
+     * OpenApiModule.forRoot({
+     *   title: 'Public API',
+     *   version: '1.0.0',
+     *   ui: true,
+     * });
+     * ```
+     */
+    static forRoot(options: OpenApiModuleOptions): ModuleType;
+    /**
+     * Registers OpenAPI providers using an async DI factory.
+     *
+     * @param options Async options factory plus optional DI `inject` token list.
+     * @returns A runtime module type that resolves options at bootstrap time.
+     *
+     * @example
+     * ```ts
+     * OpenApiModule.forRootAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config) => ({
+     *     title: config.get('APP_NAME'),
+     *     version: config.get('APP_VERSION'),
+     *   }),
+     * });
+     * ```
+     */
+    static forRootAsync(options: AsyncModuleOptions<OpenApiModuleOptions>): ModuleType;
+    private static createModule;
+}
+//# sourceMappingURL=openapi-module.d.ts.map

package/dist/openapi-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-module.d.ts","sourceRoot":"","sources":["../src/openapi-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAU,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAiC,MAAM,cAAc,CAAC;AAChH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,2BAA2B,EACjC,MAAM,qBAAqB,CAAC;AAO7B;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,WAAW,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3C,OAAO,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;IAC9D,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,eAAe,CAAC;CACpE;AAsED;;GAEG;AACH,qBAAa,aAAa;IACxB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU;IAOzD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,GAAG,UAAU;IAQlF,OAAO,CAAC,MAAM,CAAC,YAAY;CAqE5B"}