nestjs-openapi 0.1.0 → 0.1.2

package/README.md

@@ -1,35 +1,32 @@
-# nestjs-openapi
+<div align="center">
+  <img src="docs/public/logo.png" alt="nestjs-openapi" width="120" />
+  <h1>nestjs-openapi</h1>
+  <p>Static OpenAPI generation for NestJS.<br/>Analyzes TypeScript source directly—no build step, no app bootstrap.</p>
 
-Static OpenAPI generation for NestJS. Analyzes TypeScript source directly—no build step, no app bootstrap.
+  [![npm version](https://img.shields.io/npm/v/nestjs-openapi)](https://www.npmjs.com/package/nestjs-openapi)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-[![npm version](https://img.shields.io/npm/v/nestjs-openapi)](https://www.npmjs.com/package/nestjs-openapi)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+  <a href="https://nestjs-openapi.vercel.app">Documentation</a> · <a href="https://nestjs-openapi.vercel.app/docs/quick-start">Quick Start</a> · <a href="https://github.com/Newbie012/nestjs-openapi/issues">Report Bug</a>
+</div>
 
-## Why static analysis?
+<br/>
 
-|  | Runtime (`@nestjs/swagger`) | Static (`nestjs-openapi`) |
-|---|---|---|
-| Requires runtime execution | Yes | No |
-| Requires app bootstrap | Yes | No |
-| Preserves generics/unions | No | Yes |
+## Motivation
 
-## Who is this for?
+`@nestjs/swagger` relies on `reflect-metadata` at runtime, which only exposes basic type signatures. Unions, generics, and literal types are erased. To work around this, you duplicate type information in decorators:
 
-- Teams who want accurate OpenAPI from TypeScript types without runtime metadata
-- CI/CD pipelines that should not boot the app or require infrastructure
-- Projects that want OpenAPI as a build artifact or committed output
-
-## Compatibility
+```typescript
+// You already have this type
+status: 'pending' | 'shipped' | 'delivered';
 
-- NestJS 10 or 11 (decorator-based controllers)
-- TypeScript 5+
-- Node 20+
+// But you also need this decorator to make the spec accurate
+@ApiProperty({ enum: ['pending', 'shipped', 'delivered'] })
+status: 'pending' | 'shipped' | 'delivered';
+```
 
-## Limitations
+When they drift apart, your spec lies about your API.
 
-- Dynamic route registration at runtime is not supported
-- Response shortcut decorators like `@ApiOkResponse()` are not read
-- Controller versioning via `@Controller({ path, version })` is not supported
+**nestjs-openapi** reads your TypeScript source directly using the AST. Your types are your spec—no duplication, no drift.
 
 ## Quick start
 
@@ -59,27 +56,16 @@ Generate:
 npx nestjs-openapi generate
 ```
 
-## Migration from @nestjs/swagger
-
-1. Keep your controllers and route decorators as-is.
-2. Move `DocumentBuilder` config into `openapi.config.ts`.
-3. Replace response shortcuts with `@ApiResponse({ status: ... })`.
-4. (Optional) Use `OpenApiModule` to serve the generated spec at runtime.
-
-See the full guide in the docs.
-
 ## Documentation
 
-Full documentation: **[nestjs-openapi.dev](https://nestjs-openapi.dev)**
+Full documentation at **[nestjs-openapi.vercel.app](https://nestjs-openapi.vercel.app)**
 
-- [Configuration](https://nestjs-openapi.dev/docs/guides/configuration)
-- [Security schemes](https://nestjs-openapi.dev/docs/guides/security)
-- [Validation extraction](https://nestjs-openapi.dev/docs/guides/validation)
-- [Serving specs at runtime](https://nestjs-openapi.dev/docs/guides/serving)
-- [Migration guide](https://nestjs-openapi.dev/docs/recipes/migration)
-- [CI/CD recipe](https://nestjs-openapi.dev/docs/recipes/ci-cd)
-- [FAQ](https://nestjs-openapi.dev/docs/faq)
-- [Decorator support](https://nestjs-openapi.dev/docs/guides/decorators)
+- [Configuration](https://nestjs-openapi.vercel.app/docs/guides/configuration)
+- [Security schemes](https://nestjs-openapi.vercel.app/docs/guides/security)
+- [Serving specs at runtime](https://nestjs-openapi.vercel.app/docs/guides/serving)
+- [Migration from @nestjs/swagger](https://nestjs-openapi.vercel.app/docs/recipes/migration)
+- [CI/CD recipe](https://nestjs-openapi.vercel.app/docs/recipes/ci-cd)
+- [FAQ](https://nestjs-openapi.vercel.app/docs/faq)
 
 ## Contributing
 

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.DlNMM8Zq.mjs';
+import { g as generate, e as formatValidationResult } from './shared/nestjs-openapi.yWMsjl_8.mjs';
 import minimist from 'minimist';
 import { relative } from 'node:path';
 import { createRequire } from 'node:module';
@@ -9,7 +9,7 @@ import 'node:fs';
 import 'ts-morph';
 import 'glob';
 import 'js-yaml';
-import './shared/nestjs-openapi.B1bBy_tG.mjs';
+import './shared/nestjs-openapi.CBj9xHZ4.mjs';
 import 'ts-json-schema-generator';
 import 'node:crypto';
 import 'node:url';

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.BYUrTaMo.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.BYUrTaMo.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.OhsaHu32.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.OhsaHu32.mjs';
 import { DynamicModule } from '@nestjs/common';
 import { Project, SourceFile, ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
 

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.BYUrTaMo.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.BYUrTaMo.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.OhsaHu32.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.OhsaHu32.js';
 import { DynamicModule } from '@nestjs/common';
 import { Project, SourceFile, ClassDeclaration, MethodDeclaration, Decorator, Symbol, ObjectLiteralExpression, Expression } from 'ts-morph';
 

package/dist/index.mjs

@@ -1,10 +1,10 @@
-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.DlNMM8Zq.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.yWMsjl_8.mjs';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { Module } from '@nestjs/common';
 export { generateAsync, generate as generateEffect } from './internal.mjs';
-import { P as ProjectInitError, E as EntryNotFoundError } from './shared/nestjs-openapi.B1bBy_tG.mjs';
-export { a as ConfigLoadError, C as ConfigNotFoundError, b as ConfigValidationError, I as InvalidMethodError, c as getAllControllers, q as getArrayInitializer, o as getControllerMethodInfos, e as getControllerName, d as getControllerPrefix, j as getControllerTags, h as getDecoratorName, k as getHttpDecorator, f as getHttpMethods, m as getMethodInfo, w as getModuleDecoratorArg, z as getModuleMetadata, g as getModules, s as getStringLiteralValue, u as getSymbolFromIdentifier, l as isHttpDecorator, i as isHttpMethod, v as isModuleClass, n as normalizePath, y as resolveArrayOfClasses, x as resolveClassFromExpression, r as resolveClassFromSymbol, t as transformMethod, p as transformMethods } from './shared/nestjs-openapi.B1bBy_tG.mjs';
+import { P as ProjectInitError, E as EntryNotFoundError } from './shared/nestjs-openapi.CBj9xHZ4.mjs';
+export { a as ConfigLoadError, C as ConfigNotFoundError, b as ConfigValidationError, I as InvalidMethodError, c as getAllControllers, q as getArrayInitializer, o as getControllerMethodInfos, e as getControllerName, d as getControllerPrefix, j as getControllerTags, h as getDecoratorName, k as getHttpDecorator, f as getHttpMethods, m as getMethodInfo, w as getModuleDecoratorArg, z as getModuleMetadata, g as getModules, s as getStringLiteralValue, u as getSymbolFromIdentifier, l as isHttpDecorator, i as isHttpMethod, v as isModuleClass, n as normalizePath, y as resolveArrayOfClasses, x as resolveClassFromExpression, r as resolveClassFromSymbol, t as transformMethod, p as transformMethods } from './shared/nestjs-openapi.CBj9xHZ4.mjs';
 import { Context, Effect, Layer } from 'effect';
 import { Project } from 'ts-morph';
 import 'glob';

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.BYUrTaMo.mjs';
+export { G as GenerateOptions, g as generate, d as generateAsync } from './shared/nestjs-openapi.OhsaHu32.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.BYUrTaMo.js';
+export { G as GenerateOptions, g as generate, d as generateAsync } from './shared/nestjs-openapi.OhsaHu32.js';

package/dist/internal.mjs

@@ -1,6 +1,6 @@
 import { Effect } from 'effect';
 import { Project } from 'ts-morph';
-import { E as EntryNotFoundError, g as getModules, o as getControllerMethodInfos, p as transformMethods } from './shared/nestjs-openapi.B1bBy_tG.mjs';
+import { E as EntryNotFoundError, g as getModules, o as getControllerMethodInfos, p as transformMethods } from './shared/nestjs-openapi.CBj9xHZ4.mjs';
 
 const generate = (options) => Effect.gen(function* () {
   yield* Effect.logInfo("Starting OpenAPI generation").pipe(

package/dist/shared/{nestjs-openapi.B1bBy_tG.mjs → nestjs-openapi.CBj9xHZ4.mjs}

@@ -850,7 +850,7 @@ const isExpandableType = (typeName) => {
   if (BUILT_IN_TYPES.has(typeName.split("<")[0])) return false;
   if (typeName.includes(" | ") || typeName.includes(" & ")) return false;
   if (typeName.endsWith("[]")) return false;
-  return /^[A-Z][a-zA-Z0-9]*$/.test(typeName);
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(typeName);
 };
 const tsTypeToString = (typeText) => {
   const trimmed = typeText.trim();
@@ -1306,10 +1306,16 @@ const tsTypeToOpenApiSchema = (tsType) => {
     }
   }
   if (trimmed.includes(" | ")) {
-    const types = trimmed.split(" | ").map((t) => t.trim());
-    return {
-      oneOf: types.map((type) => tsTypeToOpenApiSchema(type))
-    };
+    const allMembers = trimmed.split(" | ").map((t) => t.trim());
+    const hasNull = allMembers.includes("null");
+    const types = allMembers.filter((t) => t !== "undefined" && t !== "null");
+    if (types.length === 0) return { type: "object" };
+    const schema = types.length === 1 ? tsTypeToOpenApiSchema(types[0]) : { oneOf: types.map((type) => tsTypeToOpenApiSchema(type)) };
+    if (!hasNull) return schema;
+    if (schema.$ref) {
+      return { allOf: [{ $ref: schema.$ref }], nullable: true };
+    }
+    return { ...schema, nullable: true };
   }
   switch (trimmed.toLowerCase()) {
     case "string":
@@ -1327,6 +1333,7 @@ const tsTypeToOpenApiSchema = (tsType) => {
       return { type: "object" };
     case "unknown":
     case "any":
+    case "object":
       return { type: "object" };
   }
   if (trimmed === "StreamableFile" || trimmed === "Buffer" || trimmed === "Readable" || trimmed === "ReadableStream") {
@@ -1345,7 +1352,7 @@ const tsTypeToOpenApiSchema = (tsType) => {
       type: "object"
     };
   }
-  if (trimmed.match(/^[A-Z][a-zA-Z0-9]*(<[^>]+>)?$/)) {
+  if (trimmed.match(/^[a-zA-Z_$][a-zA-Z0-9_$]*(<[^>]+>)?$/)) {
     return { $ref: `#/components/schemas/${trimmed}` };
   }
   return { type: "object" };

package/dist/shared/{nestjs-openapi.BYUrTaMo.d.mts → nestjs-openapi.OhsaHu32.d.mts}

@@ -173,9 +173,12 @@ interface OpenApiSchema {
     readonly format?: string;
     readonly $ref?: string;
     readonly oneOf?: readonly OpenApiSchema[];
+    readonly allOf?: readonly OpenApiSchema[];
     readonly items?: OpenApiSchema;
     readonly properties?: Record<string, OpenApiSchema>;
     readonly required?: readonly string[];
+    /** OpenAPI 3.0 nullable flag */
+    readonly nullable?: boolean;
 }
 declare const OpenApiOperation: Schema.Struct<{
     operationId: typeof Schema.String;

package/dist/shared/{nestjs-openapi.BYUrTaMo.d.ts → nestjs-openapi.OhsaHu32.d.ts}

@@ -173,9 +173,12 @@ interface OpenApiSchema {
     readonly format?: string;
     readonly $ref?: string;
     readonly oneOf?: readonly OpenApiSchema[];
+    readonly allOf?: readonly OpenApiSchema[];
     readonly items?: OpenApiSchema;
     readonly properties?: Record<string, OpenApiSchema>;
     readonly required?: readonly string[];
+    /** OpenAPI 3.0 nullable flag */
+    readonly nullable?: boolean;
 }
 declare const OpenApiOperation: Schema.Struct<{
     operationId: typeof Schema.String;

package/dist/shared/{nestjs-openapi.DlNMM8Zq.mjs → nestjs-openapi.yWMsjl_8.mjs}

@@ -4,7 +4,7 @@ import { join, dirname, resolve } from 'node:path';
 import { Project } from 'ts-morph';
 import { globSync, glob } from 'glob';
 import yaml from 'js-yaml';
-import { C as ConfigNotFoundError, a as ConfigLoadError, b as ConfigValidationError, p as transformMethods, A as extractClassConstraints, B as getRequiredProperties, D as mergeValidationConstraints, E as EntryNotFoundError, g as getModules, o as getControllerMethodInfos } from './nestjs-openapi.B1bBy_tG.mjs';
+import { C as ConfigNotFoundError, a as ConfigLoadError, b as ConfigValidationError, p as transformMethods, A as extractClassConstraints, B as getRequiredProperties, D as mergeValidationConstraints, E as EntryNotFoundError, g as getModules, o as getControllerMethodInfos } from './nestjs-openapi.CBj9xHZ4.mjs';
 import { createGenerator } from 'ts-json-schema-generator';
 import { randomUUID } from 'node:crypto';
 import { pathToFileURL } from 'node:url';
@@ -466,6 +466,12 @@ const extractReferencedSchemas = (paths) => {
     if (schema.oneOf) {
       schema.oneOf.forEach(extractFromSchema);
     }
+    if (schema.allOf) {
+      schema.allOf.forEach(extractFromSchema);
+    }
+    if (schema.anyOf) {
+      schema.anyOf.forEach(extractFromSchema);
+    }
     if (schema.properties) {
       Object.values(schema.properties).forEach(extractFromSchema);
     }
@@ -529,7 +535,14 @@ const extractNestedReferences = (schemas, knownSchemas) => {
 };
 const convertToOpenApiSchema = (schema) => {
   const result = {};
-  if (schema.type) result["type"] = schema.type;
+  if (Array.isArray(schema.type)) {
+    const nonNull = schema.type.filter((t) => t !== "null");
+    const isNullable = nonNull.length < schema.type.length;
+    result["type"] = nonNull.length === 1 ? nonNull[0] : schema.type;
+    if (isNullable && nonNull.length === 1) result["nullable"] = true;
+  } else if (schema.type) {
+    result["type"] = schema.type;
+  }
   if (schema.format) result["format"] = schema.format;
   if (schema.$ref) {
     result["$ref"] = schema.$ref.replace(
@@ -700,14 +713,81 @@ const transformSchemasForVersion = (schemas, version) => {
     ])
   );
 };
+const transformOperationToV31 = (operation) => {
+  const parameters = operation.parameters?.map((param) => ({
+    ...param,
+    schema: transformSchemaToV31(param.schema)
+  }));
+  const requestBody = operation.requestBody ? {
+    ...operation.requestBody,
+    content: Object.fromEntries(
+      Object.entries(operation.requestBody.content).map(
+        ([contentType, mediaType]) => [
+          contentType,
+          { ...mediaType, schema: transformSchemaToV31(mediaType.schema) }
+        ]
+      )
+    )
+  } : void 0;
+  const responses = Object.fromEntries(
+    Object.entries(operation.responses).map(([code, response]) => [
+      code,
+      response.content ? {
+        ...response,
+        content: Object.fromEntries(
+          Object.entries(response.content).map(
+            ([contentType, mediaType]) => [
+              contentType,
+              {
+                ...mediaType,
+                schema: transformSchemaToV31(mediaType.schema)
+              }
+            ]
+          )
+        )
+      } : response
+    ])
+  );
+  return {
+    ...operation,
+    ...parameters && { parameters },
+    ...requestBody && { requestBody },
+    responses
+  };
+};
+const HTTP_METHODS = /* @__PURE__ */ new Set([
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+]);
+const transformPathsForVersion = (paths, version) => {
+  if (version === "3.0.3") return paths;
+  return Object.fromEntries(
+    Object.entries(paths).map(([path, pathItem]) => [
+      path,
+      Object.fromEntries(
+        Object.entries(pathItem).map(
+          ([key, value]) => HTTP_METHODS.has(key) ? [key, transformOperationToV31(value)] : [key, value]
+        )
+      )
+    ])
+  );
+};
 const transformSpecForVersion = (spec, version) => {
   if (version === "3.0.3") {
     return { ...spec, openapi: version };
   }
   const transformedSchemas = spec.components?.schemas ? transformSchemasForVersion(spec.components.schemas, version) : void 0;
+  const transformedPaths = transformPathsForVersion(spec.paths, version);
   return {
     ...spec,
     openapi: version,
+    paths: transformedPaths,
     ...transformedSchemas && {
       components: {
         ...spec.components,

package/package.json

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