nestjs-openapi 0.1.3 → 0.1.4

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import 'tsx';
-import { g as generate, e as formatValidationResult } from './shared/nestjs-openapi.D2c4bMP5.mjs';
+import { g as generate, e as formatValidationResult } from './shared/nestjs-openapi.CUKGdNSM.mjs';
 import minimist from 'minimist';
 import { relative } from 'node:path';
 import { createRequire } from 'node:module';

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Effect, Context, Layer, Option } from 'effect';
-import { C as ConfigNotFoundError, O as OpenApiGeneratorConfig, a as ConfigError, R as ResolvedConfig, P as ProjectError, b as ProjectInitError, E as EntryNotFoundError, M as MethodInfo, c as OpenApiPaths$1 } from './shared/nestjs-openapi.t3iwzrrT.mjs';
-export { A as AnalysisError, i as ConfigLoadError, j as ConfigValidationError, G as GenerateOptions, k as GeneratorError, H as HttpMethod, I as InvalidMethodError, e as ParameterLocation, f as ResolvedParameter, h as ReturnTypeInfo, d as generateAsync, g as generateEffect } from './shared/nestjs-openapi.t3iwzrrT.mjs';
+import { C as ConfigNotFoundError, O as OpenApiGeneratorConfig, a as ConfigError, R as ResolvedConfig, P as ProjectError, b as ProjectInitError, E as EntryNotFoundError, M as MethodInfo, c as OpenApiPaths$1 } from './shared/nestjs-openapi.ClTIhsb-.mjs';
+export { A as AnalysisError, i as ConfigLoadError, j as ConfigValidationError, G as GenerateOptions, k as GeneratorError, H as HttpMethod, I as InvalidMethodError, e as ParameterLocation, f as ResolvedParameter, h as ReturnTypeInfo, d as generateAsync, g as generateEffect } from './shared/nestjs-openapi.ClTIhsb-.mjs';
 import { DynamicModule } from '@nestjs/common';
 import { Project, SourceFile, ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
 
@@ -275,6 +275,23 @@ interface OptionsConfig {
      * Query parameter handling options.
      */
     readonly query?: QueryOptions;
+    /**
+     * Schema generation and normalization options.
+     */
+    readonly schemas?: SchemaOptions;
+}
+/**
+ * Schema generation and normalization options.
+ */
+interface SchemaOptions {
+    /**
+     * How to handle schema aliases that only redirect via `$ref`.
+     * - `"collapse"`: Rewrite refs to the final target schema and remove alias entries
+     * - `"preserve"`: Keep alias schemas as-is
+     *
+     * @default "collapse"
+     */
+    readonly aliasRefs?: 'collapse' | 'preserve';
 }
 /**
  * Query parameter handling options.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Effect, Context, Layer, Option } from 'effect';
-import { C as ConfigNotFoundError, O as OpenApiGeneratorConfig, a as ConfigError, R as ResolvedConfig, P as ProjectError, b as ProjectInitError, E as EntryNotFoundError, M as MethodInfo, c as OpenApiPaths$1 } from './shared/nestjs-openapi.t3iwzrrT.js';
-export { A as AnalysisError, i as ConfigLoadError, j as ConfigValidationError, G as GenerateOptions, k as GeneratorError, H as HttpMethod, I as InvalidMethodError, e as ParameterLocation, f as ResolvedParameter, h as ReturnTypeInfo, d as generateAsync, g as generateEffect } from './shared/nestjs-openapi.t3iwzrrT.js';
+import { C as ConfigNotFoundError, O as OpenApiGeneratorConfig, a as ConfigError, R as ResolvedConfig, P as ProjectError, b as ProjectInitError, E as EntryNotFoundError, M as MethodInfo, c as OpenApiPaths$1 } from './shared/nestjs-openapi.ClTIhsb-.js';
+export { A as AnalysisError, i as ConfigLoadError, j as ConfigValidationError, G as GenerateOptions, k as GeneratorError, H as HttpMethod, I as InvalidMethodError, e as ParameterLocation, f as ResolvedParameter, h as ReturnTypeInfo, d as generateAsync, g as generateEffect } from './shared/nestjs-openapi.ClTIhsb-.js';
 import { DynamicModule } from '@nestjs/common';
 import { Project, SourceFile, ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
 
@@ -275,6 +275,23 @@ interface OptionsConfig {
      * Query parameter handling options.
      */
     readonly query?: QueryOptions;
+    /**
+     * Schema generation and normalization options.
+     */
+    readonly schemas?: SchemaOptions;
+}
+/**
+ * Schema generation and normalization options.
+ */
+interface SchemaOptions {
+    /**
+     * How to handle schema aliases that only redirect via `$ref`.
+     * - `"collapse"`: Rewrite refs to the final target schema and remove alias entries
+     * - `"preserve"`: Keep alias schemas as-is
+     *
+     * @default "collapse"
+     */
+    readonly aliasRefs?: 'collapse' | 'preserve';
 }
 /**
  * Query parameter handling options.

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { c as categorizeBrokenRefs, d as defineConfig, f as findConfigFile, e as formatValidationResult, g as generate, b as loadAndResolveConfig, a as loadConfig, l as loadConfigFromFile, r as resolveConfig, v as validateSpec } from './shared/nestjs-openapi.D2c4bMP5.mjs';
+export { c as categorizeBrokenRefs, d as defineConfig, f as findConfigFile, e as formatValidationResult, g as generate, b as loadAndResolveConfig, a as loadConfig, l as loadConfigFromFile, r as resolveConfig, v as validateSpec } from './shared/nestjs-openapi.CUKGdNSM.mjs';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { Module } from '@nestjs/common';

package/dist/internal.d.mts

@@ -1,2 +1,2 @@
 import 'effect';
-export { G as GenerateOptions, g as generate, d as generateAsync } from './shared/nestjs-openapi.t3iwzrrT.mjs';
+export { G as GenerateOptions, g as generate, d as generateAsync } from './shared/nestjs-openapi.ClTIhsb-.mjs';

package/dist/internal.d.ts

@@ -1,2 +1,2 @@
 import 'effect';
-export { G as GenerateOptions, g as generate, d as generateAsync } from './shared/nestjs-openapi.t3iwzrrT.js';
+export { G as GenerateOptions, g as generate, d as generateAsync } from './shared/nestjs-openapi.ClTIhsb-.js';

package/dist/shared/{nestjs-openapi.D2c4bMP5.mjs → nestjs-openapi.CUKGdNSM.mjs}

@@ -450,6 +450,165 @@ const resolveNewSchemaName = (originalName, structureMapping) => {
   return originalName;
 };
 
+const COMPONENT_SCHEMA_REF_PREFIX = "#/components/schemas/";
+const ALIAS_SCHEMA_KEYS = /* @__PURE__ */ new Set(["$ref", "description"]);
+const extractSchemaRefName = (ref) => ref.startsWith(COMPONENT_SCHEMA_REF_PREFIX) ? ref.slice(COMPONENT_SCHEMA_REF_PREFIX.length) : null;
+const toSchemaRef = (name) => `${COMPONENT_SCHEMA_REF_PREFIX}${name}`;
+const isAliasSchema = (schema) => {
+  if (!schema.$ref) return false;
+  return Object.keys(schema).every(
+    (key) => ALIAS_SCHEMA_KEYS.has(key)
+  );
+};
+const rewriteSchemaRefs = (schema, rewriteRef) => {
+  const result = { ...schema };
+  if (typeof schema.$ref === "string") {
+    result["$ref"] = rewriteRef(schema.$ref);
+  }
+  if (schema.items) {
+    result["items"] = rewriteSchemaRefs(schema.items, rewriteRef);
+  }
+  if (schema.oneOf) {
+    result["oneOf"] = schema.oneOf.map(
+      (item) => rewriteSchemaRefs(item, rewriteRef)
+    );
+  }
+  if (schema.anyOf) {
+    result["anyOf"] = schema.anyOf.map(
+      (item) => rewriteSchemaRefs(item, rewriteRef)
+    );
+  }
+  if (schema.allOf) {
+    result["allOf"] = schema.allOf.map(
+      (item) => rewriteSchemaRefs(item, rewriteRef)
+    );
+  }
+  if (schema.properties) {
+    result["properties"] = Object.fromEntries(
+      Object.entries(schema.properties).map(([key, propertySchema]) => [
+        key,
+        rewriteSchemaRefs(propertySchema, rewriteRef)
+      ])
+    );
+  }
+  if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+    result["additionalProperties"] = rewriteSchemaRefs(
+      schema.additionalProperties,
+      rewriteRef
+    );
+  }
+  return result;
+};
+const rewritePathsRefs = (paths, rewriteRef) => Object.fromEntries(
+  Object.entries(paths).map(([path, methods]) => [
+    path,
+    Object.fromEntries(
+      Object.entries(methods).map(([method, operation]) => [
+        method,
+        {
+          ...operation,
+          ...operation.parameters && {
+            parameters: operation.parameters.map((parameter) => ({
+              ...parameter,
+              schema: rewriteSchemaRefs(parameter.schema, rewriteRef)
+            }))
+          },
+          ...operation.requestBody && {
+            requestBody: {
+              ...operation.requestBody,
+              content: Object.fromEntries(
+                Object.entries(operation.requestBody.content).map(
+                  ([contentType, content]) => [
+                    contentType,
+                    {
+                      ...content,
+                      schema: rewriteSchemaRefs(content.schema, rewriteRef)
+                    }
+                  ]
+                )
+              )
+            }
+          },
+          responses: Object.fromEntries(
+            Object.entries(operation.responses).map(([statusCode, response]) => [
+              statusCode,
+              response.content ? {
+                ...response,
+                content: Object.fromEntries(
+                  Object.entries(response.content).map(
+                    ([contentType, content]) => [
+                      contentType,
+                      {
+                        ...content,
+                        schema: rewriteSchemaRefs(content.schema, rewriteRef)
+                      }
+                    ]
+                  )
+                )
+              } : response
+            ])
+          )
+        }
+      ])
+    )
+  ])
+);
+const rewriteSchemasRefs = (schemas, rewriteRef) => Object.fromEntries(
+  Object.entries(schemas).map(([name, schema]) => [
+    name,
+    rewriteSchemaRefs(schema, rewriteRef)
+  ])
+);
+const resolveAliasTargets = (schemas) => {
+  const directAliases = /* @__PURE__ */ new Map();
+  for (const [name, schema] of Object.entries(schemas)) {
+    if (!isAliasSchema(schema) || !schema.$ref) continue;
+    const target = extractSchemaRefName(schema.$ref);
+    if (!target) continue;
+    directAliases.set(name, target);
+  }
+  const resolvedAliases = /* @__PURE__ */ new Map();
+  const resolveFinalTarget = (start) => {
+    const visited = /* @__PURE__ */ new Set([start]);
+    let current = start;
+    while (true) {
+      const next = directAliases.get(current);
+      if (!next) return current === start ? null : current;
+      if (!(next in schemas)) return null;
+      if (visited.has(next)) return null;
+      visited.add(next);
+      current = next;
+    }
+  };
+  for (const aliasName of directAliases.keys()) {
+    const finalTarget = resolveFinalTarget(aliasName);
+    if (!finalTarget || finalTarget === aliasName) continue;
+    resolvedAliases.set(aliasName, finalTarget);
+  }
+  return resolvedAliases;
+};
+const collapseAliasRefs = (paths, schemas) => {
+  const aliasTargets = resolveAliasTargets(schemas);
+  if (aliasTargets.size === 0) return { paths, schemas };
+  const rewriteRef = (ref) => {
+    const refName = extractSchemaRefName(ref);
+    if (!refName) return ref;
+    const finalTarget = aliasTargets.get(refName);
+    return finalTarget ? toSchemaRef(finalTarget) : ref;
+  };
+  const rewrittenPaths = rewritePathsRefs(paths, rewriteRef);
+  const rewrittenSchemas = rewriteSchemasRefs(schemas, rewriteRef);
+  const collapsedSchemas = Object.fromEntries(
+    Object.entries(rewrittenSchemas).filter(
+      ([name]) => !aliasTargets.has(name)
+    )
+  );
+  return {
+    paths: rewrittenPaths,
+    schemas: collapsedSchemas
+  };
+};
+
 const extractReferencedSchemas = (paths) => {
   const refs = /* @__PURE__ */ new Set();
   const extractFromSchema = (schema) => {
@@ -1076,6 +1235,9 @@ const OpenApiConfig = Schema.Struct({
 const QueryOptionsConfig = Schema.Struct({
   style: Schema.optional(Schema.Literal("inline", "ref"))
 });
+const SchemaOptionsConfig = Schema.Struct({
+  aliasRefs: Schema.optional(Schema.Literal("collapse", "preserve"))
+});
 const PathFilterFunction = Schema.declare(
   (input) => typeof input === "function",
   {
@@ -1092,6 +1254,7 @@ const OptionsConfig = Schema.Struct({
   extractValidation: Schema.optional(Schema.Boolean),
   excludeDecorators: Schema.optional(Schema.Array(Schema.String)),
   query: Schema.optional(QueryOptionsConfig),
+  schemas: Schema.optional(SchemaOptionsConfig),
   pathFilter: Schema.optional(PathFilter)
 });
 const OpenApiGeneratorConfig = Schema.Struct({
@@ -1110,6 +1273,7 @@ Schema.Struct({
   excludeDecorators: Schema.Array(Schema.String),
   dtoGlob: Schema.Array(Schema.String),
   extractValidation: Schema.Boolean,
+  aliasRefs: Schema.Literal("collapse", "preserve"),
   basePath: Schema.optional(Schema.String),
   pathFilter: Schema.optional(PathFilter),
   version: Schema.optional(Schema.String),
@@ -1164,7 +1328,10 @@ const DEFAULT_CONFIG = {
   },
   options: {
     excludeDecorators: ["ApiExcludeEndpoint", "ApiExcludeController"],
-    extractValidation: true
+    extractValidation: true,
+    schemas: {
+      aliasRefs: "collapse"
+    }
   },
   format: "json",
   openapi: {
@@ -1280,6 +1447,7 @@ const resolveConfig = (config) => {
     excludeDecorators: options.excludeDecorators ?? DEFAULT_CONFIG.options.excludeDecorators,
     dtoGlob,
     extractValidation: options.extractValidation ?? DEFAULT_CONFIG.options.extractValidation,
+    aliasRefs: options.schemas?.aliasRefs ?? DEFAULT_CONFIG.options.schemas.aliasRefs,
     basePath: options.basePath,
     version: openapi.version,
     info: openapi.info,
@@ -1904,6 +2072,7 @@ const generate = async (configPath, overrides) => {
   );
   const files = config.files ?? {};
   const options = config.options ?? {};
+  const aliasRefsMode = options.schemas?.aliasRefs ?? "collapse";
   const openapi = config.openapi;
   const security = openapi.security ?? {};
   const rawEntry = files.entry ?? DEFAULT_ENTRY;
@@ -2088,6 +2257,11 @@ const generate = async (configPath, overrides) => {
       }
     }
   }
+  if (aliasRefsMode === "collapse" && Object.keys(schemas).length > 0) {
+    const collapsed = collapseAliasRefs(paths, schemas);
+    paths = collapsed.paths;
+    schemas = collapsed.schemas;
+  }
   const securitySchemes = security.schemes && security.schemes.length > 0 ? buildSecuritySchemes(security.schemes) : void 0;
   const hasSchemas = Object.keys(schemas).length > 0;
   const hasSecuritySchemes = securitySchemes && Object.keys(securitySchemes).length > 0;

package/dist/shared/{nestjs-openapi.t3iwzrrT.d.mts → nestjs-openapi.ClTIhsb-.d.mts}

@@ -310,6 +310,9 @@ declare const OpenApiGeneratorConfig: Schema.Struct<{
         query: Schema.optional<Schema.Struct<{
             style: Schema.optional<Schema.Literal<["inline", "ref"]>>;
         }>>;
+        schemas: Schema.optional<Schema.Struct<{
+            aliasRefs: Schema.optional<Schema.Literal<["collapse", "preserve"]>>;
+        }>>;
         pathFilter: Schema.optional<Schema.Union<[Schema.instanceOf<RegExp>, Schema.declare<(path: string) => boolean, (path: string) => boolean, readonly [], never>]>>;
     }>>;
 }>;
@@ -322,6 +325,7 @@ declare const ResolvedConfig: Schema.Struct<{
     excludeDecorators: Schema.Array$<typeof Schema.String>;
     dtoGlob: Schema.Array$<typeof Schema.String>;
     extractValidation: typeof Schema.Boolean;
+    aliasRefs: Schema.Literal<["collapse", "preserve"]>;
     basePath: Schema.optional<typeof Schema.String>;
     pathFilter: Schema.optional<Schema.Union<[Schema.instanceOf<RegExp>, Schema.declare<(path: string) => boolean, (path: string) => boolean, readonly [], never>]>>;
     version: Schema.optional<typeof Schema.String>;

package/dist/shared/{nestjs-openapi.t3iwzrrT.d.ts → nestjs-openapi.ClTIhsb-.d.ts}

@@ -310,6 +310,9 @@ declare const OpenApiGeneratorConfig: Schema.Struct<{
         query: Schema.optional<Schema.Struct<{
             style: Schema.optional<Schema.Literal<["inline", "ref"]>>;
         }>>;
+        schemas: Schema.optional<Schema.Struct<{
+            aliasRefs: Schema.optional<Schema.Literal<["collapse", "preserve"]>>;
+        }>>;
         pathFilter: Schema.optional<Schema.Union<[Schema.instanceOf<RegExp>, Schema.declare<(path: string) => boolean, (path: string) => boolean, readonly [], never>]>>;
     }>>;
 }>;
@@ -322,6 +325,7 @@ declare const ResolvedConfig: Schema.Struct<{
     excludeDecorators: Schema.Array$<typeof Schema.String>;
     dtoGlob: Schema.Array$<typeof Schema.String>;
     extractValidation: typeof Schema.Boolean;
+    aliasRefs: Schema.Literal<["collapse", "preserve"]>;
     basePath: Schema.optional<typeof Schema.String>;
     pathFilter: Schema.optional<Schema.Union<[Schema.instanceOf<RegExp>, Schema.declare<(path: string) => boolean, (path: string) => boolean, readonly [], never>]>>;
     version: Schema.optional<typeof Schema.String>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-openapi",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Static code analysis tool to generate OpenAPI specifications from NestJS applications",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",