nestjs-openapi-next 1.0.0 → 1.0.2

package/.claude/settings.local.json

@@ -0,0 +1,25 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:spec.openapis.org)",
+      "WebFetch(domain:www.openapis.org)",
+      "WebFetch(domain:blog.stoplight.io)",
+      "WebFetch(domain:apisyouwonthate.com)",
+      "WebFetch(domain:github.com)",
+      "Bash(gh auth status:*)",
+      "Bash(gh issue create:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh issue edit:*)",
+      "Bash(npm test)",
+      "Bash(npm install)",
+      "Bash(npm test:*)",
+      "Bash(gh pr view:*)",
+      "Bash(git checkout:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\ndocs: update README with OAS 3.1/3.2 features\n\nAdd documentation for newly implemented OpenAPI 3.1/3.2 features:\n- JSON Schema Draft 2020-12 alignment\n- type as array support \\(replaces nullable\\)\n- LicenseObject.identifier\n- ServerObject.pathPrefix\n- InfoObject.tags\n- ReferenceObject summary/description override\n- exclusiveMinimum/exclusiveMaximum type change\n\nCloses #7\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git push:*)",
+      "Bash(gh pr create:*)"
+    ]
+  }
+}

package/README.md

@@ -1,39 +1,40 @@
 # nestjs-openapi-next
 
-This repository is a fork of `@nestjs/swagger` (upstream: `nestjs/swagger`).
-
-Its goal is to add first-class support for key **OpenAPI 3.2** features (see PR #1), while keeping compatibility with existing `@nestjs/swagger` usage as much as possible.
-
-> Note: `package.json` currently still uses the package name `@nestjs/swagger`. If your project also depends on the upstream package, use lockfiles / overrides / resolutions to avoid dependency conflicts.
-
-## What this fork adds (PR #1)
-
-- **HTTP `QUERY` method (OAS 3.2)**
-  - `@ApiQueryMethod()` to explicitly emit an OpenAPI `query` operation.
-- **Enhanced Tags (OAS 3.2)**
-  - `@ApiTagGroup()` to define tag metadata including `parent` and `kind`, merged into top-level `document.tags`.
-  - `DocumentBuilder.addTag()` supports an additional `summary` field.
-- **Streaming responses (OAS 3.2)**
-  - `@ApiStreamingResponse()` to emit per-item schema via `itemSchema` (e.g. SSE `text/event-stream`).
-- **OAuth 2.0 Device Authorization Flow (OAS 3.2 / RFC 8628)**
-  - OpenAPI typings include `flows.deviceAuthorization`.
-  - `@ApiSecurityDeviceFlow()` convenience decorator for security requirements.
-
-Test coverage: `test/openapi-3-2.spec.ts`.
+`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.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.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`.
+- **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-1.spec.ts`, `test/openapi-3-2.spec.ts`.
 
 ## Compatibility
 
 - **NestJS**: peerDependencies target `@nestjs/common` / `@nestjs/core` `^11.0.1`
-- **Runtime deps**: generally aligned with `@nestjs/swagger` (e.g. `reflect-metadata`, optional `class-validator` / `class-transformer`, etc.)
+- **Runtime deps**: aligned with upstream `@nestjs/swagger` (`reflect-metadata`, optional `class-validator` / `class-transformer`, etc.)
 
 ## Installation
 
-### Install from this fork (recommended for OAS 3.2 extensions)
-
-```bash
-npm i --save github:undownding/nestjs-openapi-next
-```
-
 ### Install from npm
 
 ```bash
@@ -44,98 +45,121 @@ npm i --save nestjs-openapi-next
 
 See the official Nest OpenAPI tutorial: `https://docs.nestjs.com/openapi/introduction`
 
-Typical setup (minimal skeleton):
-
 ```ts
 import { NestFactory } from '@nestjs/core';
-import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { DocumentBuilder, SwaggerModule } from 'nestjs-openapi-next';
 
-// ...
 const app = await NestFactory.create(AppModule);
 
 const config = new DocumentBuilder()
   .setTitle('Example')
   .setDescription('API description')
   .setVersion('1.0')
-  // If you want to declare OAS 3.2 in the document, set it explicitly:
+  // If you want the document to declare OAS 3.2, set it explicitly:
   .setOpenAPIVersion('3.2.0')
   .build();
 
 const document = SwaggerModule.createDocument(app, config);
 SwaggerModule.setup('api', app, document);
-
-await app.listen(3000);
 ```
 
-## OpenAPI 3.2 extensions
+## Usage
+
+### 1) `@ApiTag(options)` (recommended) and deprecation of `@ApiTagGroup()`
 
-### 1) HTTP QUERY method: `@ApiQueryMethod()`
+`@ApiTag(options)` is the primary decorator for defining tag metadata at the controller level.
 
-OAS 3.2 supports a `query` operation under `paths`. This decorator makes a Nest handler emit a `query` operation **in the generated OpenAPI document**.
+`@ApiTagGroup(options)` is kept as a backward-compatible alias, but is **deprecated** and may be removed in a future major version.
 
 ```ts
-import { Controller, Post } from '@nestjs/common';
-import { ApiQueryMethod } from '@nestjs/swagger';
+import { Controller, Get } from '@nestjs/common';
+import { ApiTag } from 'nestjs-openapi-next';
 
-@Controller()
-export class QueryController {
-  @Post('search')
-  @ApiQueryMethod()
-  search() {
-    return { ok: true };
+@ApiTag({
+  name: 'Customers',
+  summary: 'Customers'
+  // you may also set: 'x-displayName': 'Customers'
+})
+@Controller('customers')
+export class CustomersController {
+  @Get()
+  list() {
+    return [];
   }
 }
 ```
 
-- Output: `document.paths['/search'].query` is defined (and `post` is not emitted for that handler).
-- Important: this does **not** change Nest routing at runtime — it only affects the generated OpenAPI document.
+### 2) Tag `x-displayName` (mirrored with `summary`)
 
-### 2) Enhanced Tags: `@ApiTagGroup()`
+This fork treats tag `summary` and `x-displayName` as equivalent display fields:
 
-OAS 3.2 Enhanced Tags allow nesting and classification via `parent` and `kind`.
+- set either one;
+- the generated `document.tags` will contain **both** `summary` and `x-displayName` with the same value.
+
+### 3) Root-level `x-tagGroups` (tag grouping)
+
+#### Auto-derived (recommended)
+
+If you use tag `parent` relationships (via `@ApiTag()`), the root-level `x-tagGroups` will be derived automatically:
 
 ```ts
-import { Controller, Get } from '@nestjs/common';
-import { ApiTagGroup } from '@nestjs/swagger';
-
-@ApiTagGroup({
-  name: 'Cats',
-  summary: 'Cats',
-  description: 'Cat operations',
-  parent: 'Admin',
-  kind: 'nav'
-})
-@Controller('cats')
-export class CatsController {
-  @Get()
-  list() {
-    return [];
-  }
-}
+@ApiTag({ name: 'Customers' })
+@Controller('customers')
+export class CustomersController {}
+
+@ApiTag({ name: 'Customer Authentication', parent: 'Customers' })
+@Controller('auth')
+export class AuthController {}
 ```
 
-- `@ApiTagGroup()` also ensures operations are tagged (internally it behaves like applying `@ApiTags(name)`).
-- During scanning, tag group metadata is merged into top-level `document.tags` and then merged with tags coming from `DocumentBuilder`.
+Illustrative output:
+
+```yaml
+tags:
+  - name: Customers
+  - name: Customer Authentication
+x-tagGroups:
+  - name: Customers
+    tags:
+      - Customers
+      - Customer Authentication
+```
+
+#### Manual configuration
 
-#### `DocumentBuilder.addTag()` supports `summary`
+You can also set `x-tagGroups` explicitly via `DocumentBuilder.addTagGroup()`:
 
 ```ts
-new DocumentBuilder()
-  .addTag('Cats', 'Cat operations', undefined, 'Cats')
+const config = new DocumentBuilder()
+  .setTitle('t')
+  .setVersion('1')
+  .addTag('Customers')
+  .addTag('Customer Authentication')
+  .addTagGroup('Customers', ['Customers', 'Customer Authentication'])
   .build();
 ```
 
-Signature (adds the 4th argument compared to upstream):
+### 4) HTTP `QUERY` method: `@ApiQueryMethod()`
 
-- `addTag(name, description?, externalDocs?, summary?)`
+```ts
+import { Controller, Post } from '@nestjs/common';
+import { ApiQueryMethod } from 'nestjs-openapi-next';
 
-### 3) Streaming responses: `@ApiStreamingResponse()` (`itemSchema`)
+@Controller()
+export class QueryController {
+  @Post('search')
+  @ApiQueryMethod()
+  search() {
+    return { ok: true };
+  }
+}
+```
 
-For streaming responses (e.g. SSE), OAS 3.2 supports describing each streamed item via `itemSchema` under the media type.
+### 5) Streaming responses: `@ApiStreamingResponse()` (`itemSchema`)
 
 ```ts
 import { Controller, Get } from '@nestjs/common';
-import { ApiProperty, ApiStreamingResponse } from '@nestjs/swagger';
+import { ApiProperty, ApiStreamingResponse } from 'nestjs-openapi-next';
 
 class SseItemDto {
   @ApiProperty()
@@ -156,17 +180,11 @@ export class EventsController {
 }
 ```
 
-Result (illustrative):
-
-- `responses['200'].content['text/event-stream'].itemSchema` -> `#/components/schemas/SseItemDto`
-
-### 4) OAuth2 Device Authorization Flow: `flows.deviceAuthorization` + `@ApiSecurityDeviceFlow()`
-
-Define the OAuth2 scheme (with `flows.deviceAuthorization`) via `DocumentBuilder.addOAuth2()`, then declare per-operation requirements with the decorator.
+### 6) OAuth2 Device Authorization Flow: `flows.deviceAuthorization` + `@ApiSecurityDeviceFlow()`
 
 ```ts
 import { Controller, Get } from '@nestjs/common';
-import { ApiSecurityDeviceFlow, DocumentBuilder } from '@nestjs/swagger';
+import { ApiSecurityDeviceFlow, DocumentBuilder } from 'nestjs-openapi-next';
 
 @Controller()
 export class SecuredController {
@@ -196,15 +214,154 @@ const config = new DocumentBuilder()
   .build();
 ```
 
-Notes:
+### 7) OpenAPI 3.1 Webhooks: `@ApiWebhook()`
+
+OpenAPI 3.1 introduces a root-level `webhooks` object for out-of-band callbacks
+initiated by the API provider.
+
+This fork supports emitting webhook operations via a decorator:
+
+```ts
+import { Controller, Post } from '@nestjs/common';
+import { ApiWebhook } from '@nestjs/swagger';
+
+@Controller()
+export class StripeWebhooksController {
+  @Post('stripe')
+  @ApiWebhook('stripeEvent')
+  stripe() {
+    return { ok: true };
+  }
+}
+```
+
+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)
 
-- `@ApiSecurityDeviceFlow()` is a convenience wrapper around `@ApiSecurity(name, scopes)` for requirements.
-- The device flow scheme definition still comes from `addOAuth2({ flows: { deviceAuthorization: ... } })`.
+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;
+}
+```
 
-## Upstream relationship / migration notes
+### 12) `type` as array (OAS 3.1)
 
-- The OAS 3.2 support in PR #1 is implemented as an additive extension to minimize breaking changes.
-- If you don’t use the new decorators/fields, behavior should be broadly compatible with upstream `@nestjs/swagger`.
+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
 

package/dist/constants.d.ts

@@ -7,6 +7,7 @@ export declare const DECORATORS: {
     API_TAGS: string;
     API_TAG_GROUP: string;
     API_QUERY_METHOD: string;
+    API_WEBHOOK: string;
     API_CALLBACKS: string;
     API_PARAMETERS: string;
     API_HEADERS: string;

package/dist/constants.js

@@ -10,6 +10,7 @@ exports.DECORATORS = {
     API_TAGS: `${exports.DECORATORS_PREFIX}/apiUseTags`,
     API_TAG_GROUP: `${exports.DECORATORS_PREFIX}/apiTagGroup`,
     API_QUERY_METHOD: `${exports.DECORATORS_PREFIX}/apiQueryMethod`,
+    API_WEBHOOK: `${exports.DECORATORS_PREFIX}/apiWebhook`,
     API_CALLBACKS: `${exports.DECORATORS_PREFIX}/apiCallbacks`,
     API_PARAMETERS: `${exports.DECORATORS_PREFIX}/apiParameters`,
     API_HEADERS: `${exports.DECORATORS_PREFIX}/apiHeaders`,

package/dist/decorators/api-tag-group.decorator.d.ts

@@ -1,11 +1,15 @@
 import { TagObject } from '../interfaces/open-api-spec.interface';
-export type ApiTagGroupKind = 'audience' | 'badge' | 'nav' | (string & {});
-export interface ApiTagGroupOptions extends Pick<TagObject, 'name' | 'summary' | 'description' | 'externalDocs' | 'parent' | 'kind'> {
+export type ApiTagKind = 'audience' | 'badge' | 'nav' | (string & {});
+export type ApiTagGroupKind = ApiTagKind;
+export interface ApiTagOptions extends Pick<TagObject, 'name' | 'summary' | 'x-displayName' | 'description' | 'externalDocs' | 'parent' | 'kind'> {
     name: string;
     summary?: string;
+    'x-displayName'?: string;
     description?: string;
     externalDocs?: TagObject['externalDocs'];
     parent?: string;
-    kind?: ApiTagGroupKind;
+    kind?: ApiTagKind;
 }
-export declare function ApiTagGroup(options: ApiTagGroupOptions): ClassDecorator;
+export declare function ApiTag(options: ApiTagOptions): ClassDecorator;
+export declare function ApiTagGroup(options: ApiTagOptions): ClassDecorator;
+export type ApiTagGroupOptions = ApiTagOptions;

package/dist/decorators/api-tag-group.decorator.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiTag = ApiTag;
 exports.ApiTagGroup = ApiTagGroup;
 const constants_1 = require("../constants");
 const api_use_tags_decorator_1 = require("./api-use-tags.decorator");
-function ApiTagGroup(options) {
+function ApiTag(options) {
     return (target) => {
         const previous = Reflect.getMetadata(constants_1.DECORATORS.API_TAG_GROUP, target) || [];
         Reflect.defineMetadata(constants_1.DECORATORS.API_TAG_GROUP, [...previous, options], target);
@@ -11,3 +12,6 @@ function ApiTagGroup(options) {
         return target;
     };
 }
+function ApiTagGroup(options) {
+    return ApiTag(options);
+}

package/dist/decorators/api-webhook.decorator.d.ts

@@ -0,0 +1 @@
+export declare function ApiWebhook(name?: string): MethodDecorator;

package/dist/decorators/api-webhook.decorator.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiWebhook = ApiWebhook;
+const constants_1 = require("../constants");
+const helpers_1 = require("./helpers");
+function ApiWebhook(name) {
+    return (0, helpers_1.createMethodDecorator)(constants_1.DECORATORS.API_WEBHOOK, name !== null && name !== void 0 ? name : true);
+}

package/dist/decorators/index.d.ts

@@ -17,6 +17,7 @@ export * from './api-produces.decorator';
 export { ApiProperty, ApiPropertyOptional, ApiPropertyOptions, ApiResponseProperty } from './api-property.decorator';
 export * from './api-query.decorator';
 export * from './api-query-method.decorator';
+export * from './api-webhook.decorator';
 export * from './api-response.decorator';
 export * from './api-streaming-response.decorator';
 export * from './api-security.decorator';

package/dist/decorators/index.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "ApiPropertyOptional", { enumerable: true, get: f
 Object.defineProperty(exports, "ApiResponseProperty", { enumerable: true, get: function () { return api_property_decorator_1.ApiResponseProperty; } });
 __exportStar(require("./api-query.decorator"), exports);
 __exportStar(require("./api-query-method.decorator"), exports);
+__exportStar(require("./api-webhook.decorator"), exports);
 __exportStar(require("./api-response.decorator"), exports);
 __exportStar(require("./api-streaming-response.decorator"), exports);
 __exportStar(require("./api-security.decorator"), exports);

package/dist/document-builder.d.ts

@@ -8,13 +8,17 @@ 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;
+    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;
+    addTagGroup(name: string, tags: string[]): this;
     addExtension(extensionKey: string, extensionProperties: any, location?: ExtensionLocation): this;
     addSecurity(name: string, options: SecuritySchemeObject): this;
     addGlobalResponse(...respones: ApiResponseOptions[]): 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,8 +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, pathPrefix, variables) {
+        this.document.servers.push({
+            name,
+            url,
+            description,
+            variables,
+            pathPrefix
+        });
         return this;
     }
     setExternalDoc(description, url) {
@@ -57,14 +75,21 @@ class DocumentBuilder {
         return this;
     }
     addTag(name, description = '', externalDocs, summary) {
+        const normalizedSummary = summary;
         this.document.tags = this.document.tags.concat((0, lodash_1.pickBy)({
             name,
-            summary,
+            summary: normalizedSummary,
+            'x-displayName': normalizedSummary,
             description,
             externalDocs
         }, (0, lodash_1.negate)(lodash_1.isUndefined)));
         return this;
     }
+    addTagGroup(name, tags) {
+        const existing = this.document['x-tagGroups'] || [];
+        this.document['x-tagGroups'] = existing.concat({ name, tags });
+        return this;
+    }
     addExtension(extensionKey, extensionProperties, location = 'root') {
         if (!extensionKey.startsWith('x-')) {
             throw new Error('Extension key is not prefixed. Please ensure you prefix it with `x-`.');

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;