From 90805fb4fe2366aa64f75487d2663106ccd38ca5 Mon Sep 17 00:00:00 2001
From: mag123c <diehreo@gmail.com>
Date: Sat, 18 Oct 2025 14:29:19 +0900
Subject: [PATCH] feat(decorator): add type definition for format option

---
 lib/interfaces/open-api-spec.interface.ts   | 29 ++++++++++++++++++++-
 test/services/fixtures/create-user.dto.ts   |  3 +++
 test/services/schema-object-factory.spec.ts |  7 ++++-
 3 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/lib/interfaces/open-api-spec.interface.ts b/lib/interfaces/open-api-spec.interface.ts
index 820b16d9f..c4177934b 100644
--- a/lib/interfaces/open-api-spec.interface.ts
+++ b/lib/interfaces/open-api-spec.interface.ts
@@ -105,6 +105,33 @@ export type ParameterStyle =
   | 'pipeDelimited'
   | 'deepObject';
 
+/**
+ * OpenAPI-defined standard format values and commonly used formats.
+ *
+ * The `format` property in OpenAPI is an "open value", allowing custom formats.
+ * This type provides IDE autocomplete for standard formats while still permitting custom values.
+ *
+ * @issue https://github.com/nestjs/swagger/issues/3508
+ * @see https://swagger.io/docs/specification/data-models/data-types/
+ */
+export type SchemaObjectFormat =
+  | 'int32'
+  | 'int64'
+  | 'float'
+  | 'double'
+  | 'byte'
+  | 'binary'
+  | 'date'
+  | 'date-time'
+  | 'password'
+  | 'email'
+  | 'uuid'
+  | 'uri'
+  | 'hostname'
+  | 'ipv4'
+  | 'ipv6'
+  | (string & {});
+
 export interface BaseParameterObject {
   description?: string;
   required?: boolean;
@@ -214,7 +241,7 @@ export interface SchemaObject {
   additionalProperties?: SchemaObject | ReferenceObject | boolean;
   patternProperties?: SchemaObject | ReferenceObject | any;
   description?: string;
-  format?: string;
+  format?: SchemaObjectFormat;
   default?: any;
   title?: string;
   multipleOf?: number;
diff --git a/test/services/fixtures/create-user.dto.ts b/test/services/fixtures/create-user.dto.ts
index eb189fcb6..b00843378 100644
--- a/test/services/fixtures/create-user.dto.ts
+++ b/test/services/fixtures/create-user.dto.ts
@@ -99,6 +99,9 @@ export class CreateUserDto {
   @ApiProperty({ type: [String], format: 'uuid' })
   formatArray: string[];
 
+  @ApiProperty({ type: String, format: 'custom-format' })
+  customFormat: string;
+
   static _OPENAPI_METADATA_FACTORY() {
     return {
       tags: { type: () => [String] },
diff --git a/test/services/schema-object-factory.spec.ts b/test/services/schema-object-factory.spec.ts
index f3ab1e63a..24d23d3d5 100644
--- a/test/services/schema-object-factory.spec.ts
+++ b/test/services/schema-object-factory.spec.ts
@@ -359,6 +359,10 @@ describe('SchemaObjectFactory', () => {
               type: 'string',
               format: 'uuid'
             }
+          },
+          customFormat: {
+            type: 'string',
+            format: 'custom-format'
           }
         },
         required: [
@@ -375,7 +379,8 @@ describe('SchemaObjectFactory', () => {
           'houses',
           'createdAt',
           'amount',
-          'formatArray'
+          'formatArray',
+          'customFormat'
         ]
       });
       expect(schemas['CreateProfileDto']).toEqual({