nestjs-openapi-next 1.0.1 → 1.0.3

package/README.md

@@ -1,24 +1,32 @@
 # nestjs-openapi-next
 
 `nestjs-openapi-next` is a fork of `@nestjs/swagger` (upstream: `nestjs/swagger`).
-The goal is to keep upstream behavior as compatible as possible while adding a set of **OpenAPI 3.2** features and widely-used **OpenAPI extension fields** (`x-`) that are commonly consumed by tools like Redoc.
+The goal is to keep upstream behavior as compatible as possible while adding a set of **OpenAPI 3.1/3.2** features and widely-used **OpenAPI extension fields** (`x-`) that are commonly consumed by tools like Redoc.
 
 ## Key differences from upstream
 
-- **Richer OpenAPI 3.2 typings**
-  - e.g. `TagObject.summary`, `OAuthFlowsObject.deviceAuthorization`, etc.
+- **Richer OpenAPI 3.1/3.2 typings**
+  - e.g. `TagObject.summary`, `OAuthFlowsObject.deviceAuthorization`, `LicenseObject.identifier`, etc.
 - **Enhanced tag support**
   - `@ApiTag(options)` (class/controller-level): defines tag metadata (`summary`, `x-displayName`, `description`, `parent`, `kind`, ...) and merges it into the top-level `document.tags`.
   - `x-displayName` support for tags, mirrored with `summary` (setting either results in both fields being written with the same value).
   - Root-level `x-tagGroups` support (commonly used by Redoc). If you use `parent` to form relationships, `x-tagGroups` is auto-derived; you can also set it explicitly via `DocumentBuilder`.
-- **Additional OAS 3.2 behaviors**
+- **OAS 3.1 features**
+  - JSON Schema Draft 2020-12 alignment (e.g. `$defs`, `prefixItems`, `const`, `contentEncoding`, `contentMediaType`, `contentSchema`).
+  - `type` as array support (e.g. `type: ['string', 'null']`) with automatic `nullable` removal.
+  - `LicenseObject.identifier` field support via `DocumentBuilder.setLicense()`.
+  - `ReferenceObject` with `summary` and `description` override support.
+  - `exclusiveMinimum` / `exclusiveMaximum` as number type (changed from boolean in OAS 3.0).
+- **OAS 3.2 features**
   - HTTP `QUERY` method via `@ApiQueryMethod()` (emits `paths['/x'].query`).
   - Streaming responses via `@ApiStreamingResponse()` (`itemSchema`, e.g. SSE `text/event-stream`).
   - OAuth2 Device Authorization Flow typing + `@ApiSecurityDeviceFlow()` helper.
+  - `ServerObject.pathPrefix` field support via `DocumentBuilder.addServer()`.
+  - `InfoObject.tags` field support via `DocumentBuilder.setInfoTags()`.
 - **Convenience APIs**
   - `DocumentBuilder.addServerWithName()` for a non-standard-but-common `server.name`.
 
-Test coverage: `test/openapi-3-2.spec.ts`.
+Test coverage: `test/openapi-3-1.spec.ts`, `test/openapi-3-2.spec.ts`.
 
 ## Compatibility
 
@@ -230,6 +238,131 @@ export class StripeWebhooksController {
 The generated document will contain `document.webhooks.stripeEvent.post`, and the
 corresponding route will **not** be emitted under `document.paths`.
 
+### 8) `LicenseObject.identifier` (OAS 3.1)
+
+OAS 3.1 added an `identifier` field to `LicenseObject` for SPDX license identifiers:
+
+```ts
+const config = new DocumentBuilder()
+  .setTitle('Example')
+  .setVersion('1.0')
+  .setLicense('MIT', 'https://opensource.org/licenses/MIT', 'MIT')
+  .build();
+```
+
+This produces:
+
+```yaml
+info:
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+    identifier: MIT
+```
+
+### 9) `ServerObject.pathPrefix` (OAS 3.2)
+
+OAS 3.2 added a `pathPrefix` field to `ServerObject`:
+
+```ts
+const config = new DocumentBuilder()
+  .setTitle('Example')
+  .setVersion('1.0')
+  .addServer('https://api.example.com', 'Production', {}, '/v1')
+  .build();
+```
+
+This produces:
+
+```yaml
+servers:
+  - url: https://api.example.com
+    description: Production
+    pathPrefix: /v1
+```
+
+### 10) `InfoObject.tags` (OAS 3.2)
+
+OAS 3.2 added a `tags` field to `InfoObject` for categorizing the API itself:
+
+```ts
+const config = new DocumentBuilder()
+  .setTitle('Example')
+  .setVersion('1.0')
+  .setInfoTags(['payments', 'commerce'])
+  .build();
+```
+
+This produces:
+
+```yaml
+info:
+  title: Example
+  version: '1.0'
+  tags:
+    - payments
+    - commerce
+```
+
+### 11) `ReferenceObject` with `summary` / `description` override (OAS 3.1)
+
+OAS 3.1 allows `$ref` objects to include `summary` and `description` fields that override the referenced schema's values:
+
+```ts
+import { ApiProperty } from 'nestjs-openapi-next';
+
+class CreateUserDto {
+  @ApiProperty({
+    allOf: [
+      {
+        $ref: '#/components/schemas/BaseUser',
+        summary: 'User base fields',
+        description: 'Contains the common user properties'
+      }
+    ]
+  })
+  user: BaseUser;
+}
+```
+
+### 12) `type` as array (OAS 3.1)
+
+OAS 3.1 supports `type` as an array for union types. This replaces the `nullable` keyword:
+
+```ts
+import { ApiProperty } from 'nestjs-openapi-next';
+
+class UserDto {
+  @ApiProperty({ type: ['string', 'null'] })
+  nickname: string | null;
+}
+```
+
+This produces `type: ['string', 'null']` instead of `type: 'string', nullable: true`.
+
+### 13) JSON Schema Draft 2020-12 keywords (OAS 3.1)
+
+OAS 3.1 aligns with JSON Schema Draft 2020-12, adding support for:
+
+- `$defs` - local schema definitions
+- `prefixItems` - tuple validation (replaces `items` array form)
+- `const` - exact value matching
+- `contentEncoding` - encoding for string content (e.g., `base64`)
+- `contentMediaType` - media type for string content
+- `contentSchema` - schema for decoded content
+
+```ts
+import { ApiProperty } from 'nestjs-openapi-next';
+
+class FileDto {
+  @ApiProperty({
+    contentEncoding: 'base64',
+    contentMediaType: 'image/png'
+  })
+  data: string;
+}
+```
+
 ## License
 
 MIT (see `LICENSE`). This repository is a derivative work of the upstream `nestjs/swagger` project under the MIT license.

package/dist/document-builder.d.ts

@@ -8,11 +8,13 @@ export declare class DocumentBuilder {
     setDescription(description: string): this;
     setVersion(version: string): this;
     setTermsOfService(termsOfService: string): this;
+    setInfoTags(tags: string[]): this;
     setContact(name: string, url: string, email: string): this;
     setLicense(name: string, url: string): this;
+    setLicenseWithIdentifier(name: string, identifier: string): this;
     setOpenAPIVersion(version: string): this;
-    addServer(url: string, description?: string, variables?: Record<string, ServerVariableObject>): this;
-    addServerWithName(name: string, url: string, description?: string, variables?: Record<string, ServerVariableObject>): this;
+    addServer(url: string, description?: string, pathPrefix?: string, variables?: Record<string, ServerVariableObject>): this;
+    addServerWithName(name: string, url: string, description?: string, pathPrefix?: string, variables?: Record<string, ServerVariableObject>): this;
     setExternalDoc(description: string, url: string): this;
     setBasePath(path: string): this;
     addTag(name: string, description?: string, externalDocs?: ExternalDocumentationObject, summary?: string): this;

package/dist/document-builder.js

@@ -27,6 +27,10 @@ class DocumentBuilder {
         this.document.info.termsOfService = termsOfService;
         return this;
     }
+    setInfoTags(tags) {
+        this.document.info.tags = tags;
+        return this;
+    }
     setContact(name, url, email) {
         this.document.info.contact = { name, url, email };
         return this;
@@ -35,6 +39,10 @@ class DocumentBuilder {
         this.document.info.license = { name, url };
         return this;
     }
+    setLicenseWithIdentifier(name, identifier) {
+        this.document.info.license = { name, identifier };
+        return this;
+    }
     setOpenAPIVersion(version) {
         if (version.match(/^\d\.\d\.\d$/)) {
             this.document.openapi = version;
@@ -44,12 +52,18 @@ class DocumentBuilder {
         }
         return this;
     }
-    addServer(url, description, variables) {
-        this.document.servers.push({ url, description, variables });
+    addServer(url, description, pathPrefix, variables) {
+        this.document.servers.push({ url, description, variables, pathPrefix });
         return this;
     }
-    addServerWithName(name, url, description, variables) {
-        this.document.servers.push({ name, url, description, variables });
+    addServerWithName(name, url, description, pathPrefix, variables) {
+        this.document.servers.push({
+            name,
+            url,
+            description,
+            variables,
+            pathPrefix
+        });
         return this;
     }
     setExternalDoc(description, url) {

package/dist/explorers/api-parameters.explorer.d.ts

@@ -6,6 +6,29 @@ export declare const exploreApiParametersMetadata: (schemas: Record<string, Sche
         schema: {
             type: string;
             items: any;
+            $schema?: string;
+            $id?: string;
+            $defs?: Record<string, SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject>;
+            $dynamicAnchor?: string;
+            $dynamicRef?: string;
+            $anchor?: string;
+            const?: any;
+            contentMediaType?: string;
+            contentEncoding?: string;
+            contentSchema?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject;
+            if?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject;
+            then?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject;
+            else?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject;
+            dependentSchemas?: Record<string, SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject>;
+            dependentRequired?: Record<string, string[]>;
+            prefixItems?: (SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject)[];
+            unevaluatedProperties?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject | boolean;
+            unevaluatedItems?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject | boolean;
+            contains?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject;
+            minContains?: number;
+            maxContains?: number;
+            $comment?: string;
+            propertyNames?: SchemaObject | import("../interfaces/open-api-spec.interface").ReferenceObject;
             nullable?: boolean;
             discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
             readOnly?: boolean;
@@ -28,9 +51,9 @@ export declare const exploreApiParametersMetadata: (schemas: Record<string, Sche
             title?: string;
             multipleOf?: number;
             maximum?: number;
-            exclusiveMaximum?: boolean;
+            exclusiveMaximum?: boolean | number;
             minimum?: number;
-            exclusiveMinimum?: boolean;
+            exclusiveMinimum?: boolean | number;
             maxLength?: number;
             minLength?: number;
             pattern?: string;

package/dist/interfaces/open-api-spec.interface.d.ts

@@ -20,6 +20,7 @@ export interface InfoObject {
     contact?: ContactObject;
     license?: LicenseObject;
     version: string;
+    tags?: string[];
 }
 export interface ContactObject {
     name?: string;
@@ -29,10 +30,12 @@ export interface ContactObject {
 export interface LicenseObject {
     name: string;
     url?: string;
+    identifier?: string;
 }
 export interface ServerObject {
     name?: string;
     url: string;
+    pathPrefix?: string;
     description?: string;
     variables?: Record<string, ServerVariableObject>;
 }
@@ -170,8 +173,33 @@ export interface TagObject {
 export type ExamplesObject = Record<string, ExampleObject | ReferenceObject>;
 export interface ReferenceObject {
     $ref: string;
+    summary?: string;
+    description?: string;
 }
 export interface SchemaObject {
+    $schema?: string;
+    $id?: string;
+    $defs?: Record<string, SchemaObject | ReferenceObject>;
+    $dynamicAnchor?: string;
+    $dynamicRef?: string;
+    $anchor?: string;
+    const?: any;
+    contentMediaType?: string;
+    contentEncoding?: string;
+    contentSchema?: SchemaObject | ReferenceObject;
+    if?: SchemaObject | ReferenceObject;
+    then?: SchemaObject | ReferenceObject;
+    else?: SchemaObject | ReferenceObject;
+    dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+    dependentRequired?: Record<string, string[]>;
+    prefixItems?: (SchemaObject | ReferenceObject)[];
+    unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+    unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+    contains?: SchemaObject | ReferenceObject;
+    minContains?: number;
+    maxContains?: number;
+    $comment?: string;
+    propertyNames?: SchemaObject | ReferenceObject;
     nullable?: boolean;
     discriminator?: DiscriminatorObject;
     readOnly?: boolean;
@@ -181,12 +209,12 @@ export interface SchemaObject {
     example?: any;
     examples?: any[] | Record<string, any>;
     deprecated?: boolean;
-    type?: string;
+    type?: string | string[];
     allOf?: (SchemaObject | ReferenceObject)[];
     oneOf?: (SchemaObject | ReferenceObject)[];
     anyOf?: (SchemaObject | ReferenceObject)[];
     not?: SchemaObject | ReferenceObject;
-    items?: SchemaObject | ReferenceObject;
+    items?: SchemaObject | ReferenceObject | boolean;
     properties?: Record<string, SchemaObject | ReferenceObject>;
     additionalProperties?: SchemaObject | ReferenceObject | boolean;
     patternProperties?: Record<string, SchemaObject | ReferenceObject> | undefined;
@@ -196,9 +224,9 @@ export interface SchemaObject {
     title?: string;
     multipleOf?: number;
     maximum?: number;
-    exclusiveMaximum?: boolean;
+    exclusiveMaximum?: boolean | number;
     minimum?: number;
-    exclusiveMinimum?: boolean;
+    exclusiveMinimum?: boolean | number;
     maxLength?: number;
     minLength?: number;
     pattern?: string;

package/dist/interfaces/schema-object-metadata.interface.d.ts

@@ -8,7 +8,7 @@ interface SchemaObjectCommonMetadata extends Omit<SchemaObject, 'type' | 'requir
     enum?: EnumAllowedTypes;
 }
 export type SchemaObjectMetadata = (SchemaObjectCommonMetadata & {
-    type?: Type<unknown> | Function | [Function] | 'array' | 'string' | 'number' | 'boolean' | 'integer' | 'null';
+    type?: Type<unknown> | Function | [Function] | 'array' | 'string' | 'number' | 'boolean' | 'integer' | 'file' | 'null';
     required?: boolean;
 }) | ({
     type?: Type<unknown> | Function | [Function] | Record<string, any>;

package/dist/services/schema-object-factory.d.ts

@@ -15,6 +15,29 @@ export declare class SchemaObjectFactory {
             type: string;
             items: {
                 $ref: string;
+                $schema?: string;
+                $id?: string;
+                $defs?: Record<string, SchemaObject | ReferenceObject>;
+                $dynamicAnchor?: string;
+                $dynamicRef?: string;
+                $anchor?: string;
+                const?: any;
+                contentMediaType?: string;
+                contentEncoding?: string;
+                contentSchema?: SchemaObject | ReferenceObject;
+                if?: SchemaObject | ReferenceObject;
+                then?: SchemaObject | ReferenceObject;
+                else?: SchemaObject | ReferenceObject;
+                dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+                dependentRequired?: Record<string, string[]>;
+                prefixItems?: (SchemaObject | ReferenceObject)[];
+                unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+                unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+                contains?: SchemaObject | ReferenceObject;
+                minContains?: number;
+                maxContains?: number;
+                $comment?: string;
+                propertyNames?: SchemaObject | ReferenceObject;
                 nullable?: boolean;
                 discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
                 readOnly?: boolean;
@@ -24,12 +47,12 @@ export declare class SchemaObjectFactory {
                 example?: any;
                 examples?: any[] | Record<string, any>;
                 deprecated?: boolean;
-                type?: string;
+                type?: string | string[];
                 allOf?: (SchemaObject | ReferenceObject)[];
                 oneOf?: (SchemaObject | ReferenceObject)[];
                 anyOf?: (SchemaObject | ReferenceObject)[];
                 not?: SchemaObject | ReferenceObject;
-                items?: SchemaObject | ReferenceObject;
+                items?: SchemaObject | ReferenceObject | boolean;
                 properties?: Record<string, SchemaObject | ReferenceObject>;
                 additionalProperties?: SchemaObject | ReferenceObject | boolean;
                 patternProperties?: Record<string, SchemaObject | ReferenceObject> | undefined;
@@ -39,9 +62,9 @@ export declare class SchemaObjectFactory {
                 title?: string;
                 multipleOf?: number;
                 maximum?: number;
-                exclusiveMaximum?: boolean;
+                exclusiveMaximum?: boolean | number;
                 minimum?: number;
-                exclusiveMinimum?: boolean;
+                exclusiveMinimum?: boolean | number;
                 maxLength?: number;
                 minLength?: number;
                 pattern?: string;
@@ -55,6 +78,8 @@ export declare class SchemaObjectFactory {
                 'x-enumNames'?: string[];
             } | {
                 $ref: string;
+                summary?: string;
+                description?: string;
             };
         };
         type?: Type<unknown>;
@@ -70,6 +95,29 @@ export declare class SchemaObjectFactory {
         name: string | number | object;
         schema: {
             $ref: string;
+            $schema?: string;
+            $id?: string;
+            $defs?: Record<string, SchemaObject | ReferenceObject>;
+            $dynamicAnchor?: string;
+            $dynamicRef?: string;
+            $anchor?: string;
+            const?: any;
+            contentMediaType?: string;
+            contentEncoding?: string;
+            contentSchema?: SchemaObject | ReferenceObject;
+            if?: SchemaObject | ReferenceObject;
+            then?: SchemaObject | ReferenceObject;
+            else?: SchemaObject | ReferenceObject;
+            dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+            dependentRequired?: Record<string, string[]>;
+            prefixItems?: (SchemaObject | ReferenceObject)[];
+            unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+            unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+            contains?: SchemaObject | ReferenceObject;
+            minContains?: number;
+            maxContains?: number;
+            $comment?: string;
+            propertyNames?: SchemaObject | ReferenceObject;
             nullable?: boolean;
             discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
             readOnly?: boolean;
@@ -79,12 +127,12 @@ export declare class SchemaObjectFactory {
             example?: any;
             examples?: any[] | Record<string, any>;
             deprecated?: boolean;
-            type?: string;
+            type?: string | string[];
             allOf?: (SchemaObject | ReferenceObject)[];
             oneOf?: (SchemaObject | ReferenceObject)[];
             anyOf?: (SchemaObject | ReferenceObject)[];
             not?: SchemaObject | ReferenceObject;
-            items?: SchemaObject | ReferenceObject;
+            items?: SchemaObject | ReferenceObject | boolean;
             properties?: Record<string, SchemaObject | ReferenceObject>;
             additionalProperties?: SchemaObject | ReferenceObject | boolean;
             patternProperties?: Record<string, SchemaObject | ReferenceObject> | undefined;
@@ -94,9 +142,9 @@ export declare class SchemaObjectFactory {
             title?: string;
             multipleOf?: number;
             maximum?: number;
-            exclusiveMaximum?: boolean;
+            exclusiveMaximum?: boolean | number;
             minimum?: number;
-            exclusiveMinimum?: boolean;
+            exclusiveMinimum?: boolean | number;
             maxLength?: number;
             minLength?: number;
             pattern?: string;
@@ -110,6 +158,8 @@ export declare class SchemaObjectFactory {
             'x-enumNames'?: string[];
         } | {
             $ref: string;
+            summary?: string;
+            description?: string;
         };
         type?: Type<unknown>;
         in?: import("../interfaces/open-api-spec.interface").ParameterLocation | "body" | "placeholder";

package/dist/services/schema-object-factory.js

@@ -305,7 +305,8 @@ class SchemaObjectFactory {
     transformToArraySchemaProperty(metadata, key, type) {
         const keysToRemove = ['type', 'enum'];
         const [movedProperties, keysToMove] = this.extractPropertyModifiers(metadata);
-        const schemaHost = Object.assign(Object.assign({}, (0, lodash_1.omit)(metadata, [...keysToRemove, ...keysToMove])), { name: metadata.name || key, type: 'array', items: (0, lodash_1.isString)(type)
+        const schemaHost = Object.assign(Object.assign({}, (0, lodash_1.omit)(metadata, [...keysToRemove, ...keysToMove])), { name: metadata.name || key, type: 'array', items: metadata.items
+                ? Object.assign(Object.assign({}, metadata.items), movedProperties) : (0, lodash_1.isString)(type)
                 ? Object.assign({ type }, movedProperties) : Object.assign(Object.assign({}, type), movedProperties) });
         schemaHost.items = (0, lodash_1.omitBy)(schemaHost.items, shared_utils_1.isUndefined);
         return schemaHost;

package/dist/services/swagger-types-mapper.d.ts

@@ -8,6 +8,29 @@ export declare class SwaggerTypesMapper {
         schema: {
             type: string;
             items: any;
+            $schema?: string;
+            $id?: string;
+            $defs?: Record<string, SchemaObject | ReferenceObject>;
+            $dynamicAnchor?: string;
+            $dynamicRef?: string;
+            $anchor?: string;
+            const?: any;
+            contentMediaType?: string;
+            contentEncoding?: string;
+            contentSchema?: SchemaObject | ReferenceObject;
+            if?: SchemaObject | ReferenceObject;
+            then?: SchemaObject | ReferenceObject;
+            else?: SchemaObject | ReferenceObject;
+            dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+            dependentRequired?: Record<string, string[]>;
+            prefixItems?: (SchemaObject | ReferenceObject)[];
+            unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+            unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+            contains?: SchemaObject | ReferenceObject;
+            minContains?: number;
+            maxContains?: number;
+            $comment?: string;
+            propertyNames?: SchemaObject | ReferenceObject;
             nullable?: boolean;
             discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
             readOnly?: boolean;
@@ -30,9 +53,9 @@ export declare class SwaggerTypesMapper {
             title?: string;
             multipleOf?: number;
             maximum?: number;
-            exclusiveMaximum?: boolean;
+            exclusiveMaximum?: boolean | number;
             minimum?: number;
-            exclusiveMinimum?: boolean;
+            exclusiveMinimum?: boolean | number;
             maxLength?: number;
             minLength?: number;
             pattern?: string;
@@ -75,6 +98,29 @@ export declare class SwaggerTypesMapper {
         schema: {
             type: string;
             items: any;
+            $schema?: string;
+            $id?: string;
+            $defs?: Record<string, SchemaObject | ReferenceObject>;
+            $dynamicAnchor?: string;
+            $dynamicRef?: string;
+            $anchor?: string;
+            const?: any;
+            contentMediaType?: string;
+            contentEncoding?: string;
+            contentSchema?: SchemaObject | ReferenceObject;
+            if?: SchemaObject | ReferenceObject;
+            then?: SchemaObject | ReferenceObject;
+            else?: SchemaObject | ReferenceObject;
+            dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+            dependentRequired?: Record<string, string[]>;
+            prefixItems?: (SchemaObject | ReferenceObject)[];
+            unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+            unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+            contains?: SchemaObject | ReferenceObject;
+            minContains?: number;
+            maxContains?: number;
+            $comment?: string;
+            propertyNames?: SchemaObject | ReferenceObject;
             nullable?: boolean;
             discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
             readOnly?: boolean;
@@ -97,9 +143,9 @@ export declare class SwaggerTypesMapper {
             title?: string;
             multipleOf?: number;
             maximum?: number;
-            exclusiveMaximum?: boolean;
+            exclusiveMaximum?: boolean | number;
             minimum?: number;
-            exclusiveMinimum?: boolean;
+            exclusiveMinimum?: boolean | number;
             maxLength?: number;
             minLength?: number;
             pattern?: string;
@@ -117,6 +163,29 @@ export declare class SwaggerTypesMapper {
         schema: {
             type: string;
             items: any;
+            $schema?: string;
+            $id?: string;
+            $defs?: Record<string, SchemaObject | ReferenceObject>;
+            $dynamicAnchor?: string;
+            $dynamicRef?: string;
+            $anchor?: string;
+            const?: any;
+            contentMediaType?: string;
+            contentEncoding?: string;
+            contentSchema?: SchemaObject | ReferenceObject;
+            if?: SchemaObject | ReferenceObject;
+            then?: SchemaObject | ReferenceObject;
+            else?: SchemaObject | ReferenceObject;
+            dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+            dependentRequired?: Record<string, string[]>;
+            prefixItems?: (SchemaObject | ReferenceObject)[];
+            unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+            unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+            contains?: SchemaObject | ReferenceObject;
+            minContains?: number;
+            maxContains?: number;
+            $comment?: string;
+            propertyNames?: SchemaObject | ReferenceObject;
             nullable?: boolean;
             discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
             readOnly?: boolean;
@@ -139,9 +208,9 @@ export declare class SwaggerTypesMapper {
             title?: string;
             multipleOf?: number;
             maximum?: number;
-            exclusiveMaximum?: boolean;
+            exclusiveMaximum?: boolean | number;
             minimum?: number;
-            exclusiveMinimum?: boolean;
+            exclusiveMinimum?: boolean | number;
             maxLength?: number;
             minLength?: number;
             pattern?: string;
@@ -168,6 +237,29 @@ export declare class SwaggerTypesMapper {
         schema: {
             type: string;
             items: any;
+            $schema?: string;
+            $id?: string;
+            $defs?: Record<string, SchemaObject | ReferenceObject>;
+            $dynamicAnchor?: string;
+            $dynamicRef?: string;
+            $anchor?: string;
+            const?: any;
+            contentMediaType?: string;
+            contentEncoding?: string;
+            contentSchema?: SchemaObject | ReferenceObject;
+            if?: SchemaObject | ReferenceObject;
+            then?: SchemaObject | ReferenceObject;
+            else?: SchemaObject | ReferenceObject;
+            dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+            dependentRequired?: Record<string, string[]>;
+            prefixItems?: (SchemaObject | ReferenceObject)[];
+            unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+            unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+            contains?: SchemaObject | ReferenceObject;
+            minContains?: number;
+            maxContains?: number;
+            $comment?: string;
+            propertyNames?: SchemaObject | ReferenceObject;
             nullable?: boolean;
             discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
             readOnly?: boolean;
@@ -190,9 +282,9 @@ export declare class SwaggerTypesMapper {
             title?: string;
             multipleOf?: number;
             maximum?: number;
-            exclusiveMaximum?: boolean;
+            exclusiveMaximum?: boolean | number;
             minimum?: number;
-            exclusiveMinimum?: boolean;
+            exclusiveMinimum?: boolean | number;
             maxLength?: number;
             minLength?: number;
             pattern?: string;
@@ -206,15 +298,38 @@ export declare class SwaggerTypesMapper {
             'x-enumNames'?: string[];
         };
         name?: string | number | object;
-        type?: import("@nestjs/common").Type<unknown> & string;
+        type?: import("@nestjs/common").Type<unknown> & (string | string[]);
         in?: import("../interfaces/open-api-spec.interface").ParameterLocation | "body" | "placeholder";
         isArray?: boolean;
-        items?: SchemaObject | (SchemaObject & ReferenceObject);
+        items?: SchemaObject & (boolean | SchemaObject | ReferenceObject);
         required?: boolean & string[];
         enum?: unknown[] & any[];
         enumName?: string;
         enumSchema?: import("../interfaces/enum-schema-attributes.interface").EnumSchemaAttributes;
         selfRequired?: boolean;
+        $schema?: string;
+        $id?: string;
+        $defs?: Record<string, SchemaObject | ReferenceObject>;
+        $dynamicAnchor?: string;
+        $dynamicRef?: string;
+        $anchor?: string;
+        const?: any;
+        contentMediaType?: string;
+        contentEncoding?: string;
+        contentSchema?: SchemaObject | ReferenceObject;
+        if?: SchemaObject | ReferenceObject;
+        then?: SchemaObject | ReferenceObject;
+        else?: SchemaObject | ReferenceObject;
+        dependentSchemas?: Record<string, SchemaObject | ReferenceObject>;
+        dependentRequired?: Record<string, string[]>;
+        prefixItems?: (SchemaObject | ReferenceObject)[];
+        unevaluatedProperties?: SchemaObject | ReferenceObject | boolean;
+        unevaluatedItems?: SchemaObject | ReferenceObject | boolean;
+        contains?: SchemaObject | ReferenceObject;
+        minContains?: number;
+        maxContains?: number;
+        $comment?: string;
+        propertyNames?: SchemaObject | ReferenceObject;
         nullable?: boolean;
         discriminator?: import("../interfaces/open-api-spec.interface").DiscriminatorObject;
         readOnly?: boolean;
@@ -237,9 +352,9 @@ export declare class SwaggerTypesMapper {
         title?: string;
         multipleOf?: number;
         maximum?: number;
-        exclusiveMaximum?: boolean;
+        exclusiveMaximum?: boolean | number;
         minimum?: number;
-        exclusiveMinimum?: boolean;
+        exclusiveMinimum?: boolean | number;
         maxLength?: number;
         minLength?: number;
         pattern?: string;

package/dist/swagger-explorer.js

@@ -196,7 +196,9 @@ class SwaggerExplorer {
             return Object.assign(Object.assign(Object.assign({ method: httpMethodKey, path: fullPath === '' ? '/' : fullPath }, (isWebhook
                 ? {
                     isWebhook: true,
-                    webhookName: typeof webhookMetadata === 'string' ? webhookMetadata : method.name
+                    webhookName: typeof webhookMetadata === 'string'
+                        ? webhookMetadata
+                        : method.name
                 }
                 : {})), { operationId: this.getOperationId(instance, methodKey, pathVersion) }), apiExtension);
         }));

package/dist/swagger-module.d.ts

@@ -3,6 +3,8 @@ import { HttpServer } from '@nestjs/common/interfaces/http/http-server.interface
 import { OpenAPIObject, SwaggerCustomOptions, SwaggerDocumentOptions } from './interfaces';
 export declare class SwaggerModule {
     private static readonly metadataLoader;
+    private static readonly HTTP_METHODS;
+    private static collectOperationTagNames;
     private static mergeWebhooks;
     private static mergeTags;
     private static buildXTagGroups;

package/dist/swagger-module.js

@@ -21,14 +21,349 @@ const normalize_rel_path_1 = require("./utils/normalize-rel-path");
 const resolve_path_util_1 = require("./utils/resolve-path.util");
 const validate_global_prefix_util_1 = require("./utils/validate-global-prefix.util");
 const validate_path_util_1 = require("./utils/validate-path.util");
+const NULL_TYPE_SCHEMA = { type: 'null' };
+function isReferenceObject(value) {
+    return !!(value === null || value === void 0 ? void 0 : value.$ref);
+}
+function isOas31OrAbove(openapi) {
+    const [majorStr, minorStr] = (openapi || '').split('.');
+    const major = Number(majorStr);
+    const minor = Number(minorStr);
+    if (Number.isNaN(major) || Number.isNaN(minor)) {
+        return false;
+    }
+    return major > 3 || (major === 3 && minor >= 1);
+}
+function appendNullOption(schemas) {
+    const hasNull = schemas.some((item) => !isReferenceObject(item) &&
+        (item.type === 'null' ||
+            (Array.isArray(item.type) && item.type.includes('null'))));
+    return hasNull ? schemas : schemas.concat(NULL_TYPE_SCHEMA);
+}
+function normalizeNullableSchema(schema) {
+    if (!schema) {
+        return schema;
+    }
+    if (isReferenceObject(schema)) {
+        return schema;
+    }
+    const converted = Object.assign({}, schema);
+    if (converted.properties) {
+        converted.properties = Object.entries(converted.properties).reduce((acc, [key, value]) => {
+            acc[key] = normalizeNullableSchema(value);
+            return acc;
+        }, {});
+    }
+    if (converted.patternProperties) {
+        converted.patternProperties = Object.entries(converted.patternProperties).reduce((acc, [key, value]) => {
+            acc[key] = normalizeNullableSchema(value);
+            return acc;
+        }, {});
+    }
+    if (converted.additionalProperties &&
+        typeof converted.additionalProperties === 'object') {
+        converted.additionalProperties = normalizeNullableSchema(converted.additionalProperties);
+    }
+    if (converted.items && typeof converted.items !== 'boolean') {
+        converted.items = normalizeNullableSchema(converted.items);
+    }
+    if (converted.allOf) {
+        converted.allOf = converted.allOf.map((item) => normalizeNullableSchema(item));
+    }
+    if (converted.oneOf) {
+        converted.oneOf = converted.oneOf.map((item) => normalizeNullableSchema(item));
+    }
+    if (converted.anyOf) {
+        converted.anyOf = converted.anyOf.map((item) => normalizeNullableSchema(item));
+    }
+    if (converted.not) {
+        converted.not = normalizeNullableSchema(converted.not);
+    }
+    const exclusiveMinimum = converted.exclusiveMinimum;
+    if (typeof exclusiveMinimum === 'boolean') {
+        if (exclusiveMinimum === true && typeof converted.minimum === 'number') {
+            converted.exclusiveMinimum = converted.minimum;
+            delete converted.minimum;
+        }
+        else {
+            delete converted.exclusiveMinimum;
+        }
+    }
+    const exclusiveMaximum = converted.exclusiveMaximum;
+    if (typeof exclusiveMaximum === 'boolean') {
+        if (exclusiveMaximum === true && typeof converted.maximum === 'number') {
+            converted.exclusiveMaximum = converted.maximum;
+            delete converted.maximum;
+        }
+        else {
+            delete converted.exclusiveMaximum;
+        }
+    }
+    const isNullable = converted.nullable === true;
+    if (converted.nullable !== undefined) {
+        delete converted.nullable;
+    }
+    if (!isNullable) {
+        return converted;
+    }
+    if (converted.type !== undefined) {
+        const types = Array.isArray(converted.type)
+            ? converted.type
+            : [converted.type];
+        converted.type = types.includes('null') ? types : [...types, 'null'];
+        return converted;
+    }
+    if (converted.oneOf) {
+        converted.oneOf = appendNullOption(converted.oneOf);
+        return converted;
+    }
+    if (converted.anyOf) {
+        converted.anyOf = appendNullOption(converted.anyOf);
+        return converted;
+    }
+    if (converted.allOf) {
+        return {
+            anyOf: appendNullOption([converted])
+        };
+    }
+    return {
+        anyOf: appendNullOption([converted])
+    };
+}
+function transformMediaType(mediaType) {
+    const transformed = Object.assign({}, mediaType);
+    if (mediaType.schema) {
+        transformed.schema = normalizeNullableSchema(mediaType.schema);
+    }
+    if (mediaType.itemSchema) {
+        transformed.itemSchema = normalizeNullableSchema(mediaType.itemSchema);
+    }
+    return transformed;
+}
+function transformContent(content) {
+    if (!content) {
+        return content;
+    }
+    return Object.entries(content).reduce((acc, [key, value]) => {
+        acc[key] = transformMediaType(value);
+        return acc;
+    }, {});
+}
+function transformParameter(parameter) {
+    if (isReferenceObject(parameter)) {
+        return parameter;
+    }
+    const transformed = Object.assign({}, parameter);
+    if (parameter.schema) {
+        transformed.schema = normalizeNullableSchema(parameter.schema);
+    }
+    if (parameter.content) {
+        transformed.content =
+            transformContent(parameter.content) || parameter.content;
+    }
+    return transformed;
+}
+function transformHeaders(headers) {
+    if (!headers) {
+        return headers;
+    }
+    return Object.entries(headers).reduce((acc, [key, value]) => {
+        if (isReferenceObject(value)) {
+            acc[key] = value;
+            return acc;
+        }
+        const header = value;
+        const transformed = Object.assign({}, header);
+        if (header.schema) {
+            transformed.schema = normalizeNullableSchema(header.schema);
+        }
+        if (header.content) {
+            transformed.content = transformContent(header.content) || header.content;
+        }
+        acc[key] = transformed;
+        return acc;
+    }, {});
+}
+function transformRequestBody(requestBody) {
+    if (isReferenceObject(requestBody)) {
+        return requestBody;
+    }
+    const transformed = Object.assign({}, requestBody);
+    if (requestBody.content) {
+        transformed.content =
+            transformContent(requestBody.content) || requestBody.content;
+    }
+    return transformed;
+}
+function transformResponse(response) {
+    if (isReferenceObject(response)) {
+        return response;
+    }
+    const transformed = Object.assign({}, response);
+    if (response.content) {
+        transformed.content =
+            transformContent(response.content) || response.content;
+    }
+    if (response.headers) {
+        transformed.headers =
+            transformHeaders(response.headers) || response.headers;
+    }
+    return transformed;
+}
+function transformResponses(responses) {
+    return Object.entries(responses).reduce((acc, [status, response]) => {
+        if (response === undefined) {
+            acc[status] = response;
+            return acc;
+        }
+        acc[status] = transformResponse(response);
+        return acc;
+    }, {});
+}
+function transformCallbacks(callbacks) {
+    return Object.entries(callbacks).reduce((acc, [name, callback]) => {
+        if (isReferenceObject(callback)) {
+            acc[name] = callback;
+            return acc;
+        }
+        const transformedCallback = {};
+        Object.entries(callback).forEach(([path, pathItem]) => {
+            transformedCallback[path] = transformPathItem(pathItem);
+        });
+        acc[name] = transformedCallback;
+        return acc;
+    }, {});
+}
+function transformOperation(operation) {
+    const transformed = Object.assign({}, operation);
+    if (operation.parameters) {
+        transformed.parameters = operation.parameters.map(transformParameter);
+    }
+    if (operation.requestBody) {
+        transformed.requestBody = transformRequestBody(operation.requestBody);
+    }
+    if (operation.responses) {
+        transformed.responses = transformResponses(operation.responses);
+    }
+    if (operation.callbacks) {
+        transformed.callbacks = transformCallbacks(operation.callbacks);
+    }
+    return transformed;
+}
+function transformPathItem(pathItem) {
+    const transformed = Object.assign({}, pathItem);
+    if (pathItem.parameters) {
+        transformed.parameters = pathItem.parameters.map(transformParameter);
+    }
+    const operationKeys = [
+        'get',
+        'put',
+        'post',
+        'delete',
+        'options',
+        'head',
+        'patch',
+        'trace',
+        'search',
+        'query'
+    ];
+    operationKeys.forEach((operationKey) => {
+        const operation = pathItem[operationKey];
+        if (operation) {
+            transformed[operationKey] = transformOperation(operation);
+        }
+    });
+    return transformed;
+}
+function transformPathItems(paths) {
+    if (!paths) {
+        return paths;
+    }
+    return Object.entries(paths).reduce((acc, [path, pathItem]) => {
+        acc[path] = transformPathItem(pathItem);
+        return acc;
+    }, {});
+}
+function normalizeNullableForOas31(document) {
+    var _a, _b, _c, _d, _e, _f;
+    if ((_a = document.components) === null || _a === void 0 ? void 0 : _a.schemas) {
+        Object.entries(document.components.schemas).forEach(([name, schema]) => {
+            document.components.schemas[name] = normalizeNullableSchema(schema);
+        });
+    }
+    if ((_b = document.components) === null || _b === void 0 ? void 0 : _b.parameters) {
+        Object.entries(document.components.parameters).forEach(([name, parameter]) => {
+            document.components.parameters[name] = transformParameter(parameter);
+        });
+    }
+    if ((_c = document.components) === null || _c === void 0 ? void 0 : _c.requestBodies) {
+        Object.entries(document.components.requestBodies).forEach(([name, body]) => {
+            document.components.requestBodies[name] = transformRequestBody(body);
+        });
+    }
+    if ((_d = document.components) === null || _d === void 0 ? void 0 : _d.responses) {
+        Object.entries(document.components.responses).forEach(([name, response]) => {
+            document.components.responses[name] = transformResponse(response);
+        });
+    }
+    if ((_e = document.components) === null || _e === void 0 ? void 0 : _e.headers) {
+        document.components.headers =
+            transformHeaders(document.components.headers) ||
+                document.components.headers;
+    }
+    if ((_f = document.components) === null || _f === void 0 ? void 0 : _f.callbacks) {
+        document.components.callbacks = transformCallbacks(document.components.callbacks);
+    }
+    document.paths = transformPathItems(document.paths) || {};
+    if (document.webhooks) {
+        document.webhooks = transformPathItems(document.webhooks);
+    }
+}
 class SwaggerModule {
+    static collectOperationTagNames(paths, webhooks) {
+        const names = [];
+        const seen = new Set();
+        const collectFromItems = (items) => {
+            if (!items) {
+                return;
+            }
+            for (const pathItem of Object.values(items)) {
+                if (!pathItem || typeof pathItem !== 'object') {
+                    continue;
+                }
+                for (const [key, operation] of Object.entries(pathItem)) {
+                    if (!SwaggerModule.HTTP_METHODS.has(String(key).toLowerCase())) {
+                        continue;
+                    }
+                    const tags = operation === null || operation === void 0 ? void 0 : operation.tags;
+                    if (!Array.isArray(tags)) {
+                        continue;
+                    }
+                    for (const t of tags) {
+                        if (typeof t !== 'string') {
+                            continue;
+                        }
+                        const trimmed = t.trim();
+                        if (!trimmed || seen.has(trimmed)) {
+                            continue;
+                        }
+                        seen.add(trimmed);
+                        names.push(trimmed);
+                    }
+                }
+            }
+        };
+        collectFromItems(paths);
+        collectFromItems(webhooks);
+        return names;
+    }
     static mergeWebhooks(configWebhooks, scannedWebhooks) {
         if (!configWebhooks && !scannedWebhooks) {
             return undefined;
         }
         return (0, assign_two_levels_deep_1.assignTwoLevelsDeep)({}, configWebhooks || {}, scannedWebhooks || {});
     }
-    static mergeTags(configTags, scannedTags) {
+    static mergeTags(configTags, scannedTags, operationTagNames) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         const byName = new Map();
         for (const tag of configTags || []) {
@@ -55,6 +390,14 @@ class SwaggerModule {
             merged.kind = (_j = existing.kind) !== null && _j !== void 0 ? _j : tag.kind;
             byName.set(tag.name, merged);
         }
+        if (byName.size > 0) {
+            for (const name of operationTagNames || []) {
+                if (!name || byName.has(name)) {
+                    continue;
+                }
+                byName.set(name, { name });
+            }
+        }
         const merged = [...byName.values()];
         return merged.length > 0 ? merged : undefined;
     }
@@ -73,8 +416,16 @@ class SwaggerModule {
                 groupToTags.set(parent, []);
                 groupToSeen.set(parent, new Set());
             }
-            const list = groupToTags.get(parent);
-            const seen = groupToSeen.get(parent);
+            let list = groupToTags.get(parent);
+            if (!list) {
+                list = [];
+                groupToTags.set(parent, list);
+            }
+            let seen = groupToSeen.get(parent);
+            if (!seen) {
+                seen = new Set();
+                groupToSeen.set(parent, seen);
+            }
             if (!seen.has(tag.name)) {
                 seen.add(tag.name);
                 list.push(tag.name);
@@ -104,9 +455,13 @@ class SwaggerModule {
         const swaggerScanner = new swagger_scanner_1.SwaggerScanner();
         const document = swaggerScanner.scanApplication(app, options);
         document.components = (0, assign_two_levels_deep_1.assignTwoLevelsDeep)({}, config.components, document.components);
-        const mergedTags = SwaggerModule.mergeTags(config.tags, document.tags);
+        const operationTagNames = SwaggerModule.collectOperationTagNames(document.paths, document.webhooks);
+        const mergedTags = SwaggerModule.mergeTags(config.tags, document.tags, operationTagNames);
         const mergedWebhooks = SwaggerModule.mergeWebhooks(config.webhooks, document.webhooks);
         const mergedDocument = Object.assign(Object.assign(Object.assign(Object.assign({ openapi: '3.0.0', paths: {} }, config), document), (mergedTags ? { tags: mergedTags } : {})), (mergedWebhooks ? { webhooks: mergedWebhooks } : {}));
+        if (isOas31OrAbove(mergedDocument.openapi)) {
+            normalizeNullableForOas31(mergedDocument);
+        }
         if (mergedDocument['x-tagGroups'] === undefined) {
             const xTagGroups = SwaggerModule.buildXTagGroups(mergedDocument.tags);
             if (xTagGroups) {
@@ -281,3 +636,13 @@ class SwaggerModule {
 }
 exports.SwaggerModule = SwaggerModule;
 SwaggerModule.metadataLoader = new metadata_loader_1.MetadataLoader();
+SwaggerModule.HTTP_METHODS = new Set([
+    'get',
+    'put',
+    'post',
+    'delete',
+    'options',
+    'head',
+    'patch',
+    'trace'
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-openapi-next",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A fork of @nestjs/swagger support OAS 3.2",
   "author": "undownding",
   "license": "MIT",
@@ -32,14 +32,14 @@
     "js-yaml": "4.1.1",
     "lodash": "4.17.21",
     "path-to-regexp": "8.3.0",
-    "swagger-ui-dist": "5.30.2"
+    "swagger-ui-dist": "5.31.0"
   },
   "devDependencies": {
     "@commitlint/cli": "20.3.0",
     "@commitlint/config-angular": "20.3.0",
     "@eslint/eslintrc": "3.3.3",
     "@eslint/js": "9.39.2",
-    "@fastify/static": "8.3.0",
+    "@fastify/static": "9.0.0",
     "@nestjs/common": "11.1.11",
     "@nestjs/core": "11.1.11",
     "@nestjs/platform-express": "11.1.11",
@@ -64,15 +64,15 @@
     "prettier": "3.7.4",
     "prettier-v2": "npm:prettier@2.8.8",
     "reflect-metadata": "0.2.2",
-    "release-it": "19.2.2",
-    "supertest": "7.1.4",
+    "release-it": "19.2.3",
+    "supertest": "7.2.2",
     "swagger-parser": "10.0.3",
     "ts-jest": "29.4.6",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.51.0"
+    "typescript-eslint": "8.52.0"
   },
   "peerDependencies": {
-    "@fastify/static": "^8.0.0",
+    "@fastify/static": "^8.0.0 || ^9.0.0",
     "@nestjs/common": "^11.0.1",
     "@nestjs/core": "^11.0.1",
     "class-transformer": "*",