Merge pull request #1111 from samchon/features/description

Close #1110: support `@description` tag in JSON schema.

benchmark/package.json

@@ -72,6 +72,6 @@
     "suppress-warnings": "^1.0.2",
     "tstl": "^3.0.0",
     "uuid": "^9.0.1",
-    "typia": "../typia-6.1.1.tgz"
+    "typia": "../typia-6.1.2.tgz"
   }
 }

debug/features/description.ts

@@ -0,0 +1,34 @@
+import typia from "typia";
+
+/**
+ * @title Something DTO
+ * @description This is a description of the Something DTO.
+ *
+ *              Let's fill the content of it.
+ * @author Samchon
+ */
+interface Something {
+  /**
+   * This is the title.
+   *
+   * This is the description.
+   */
+  id: string;
+
+  /**
+   * This is not the description.
+   *
+   * @title Name
+   * @description This is the description of the name
+   */
+  name: string;
+
+  /**
+   * @description No title.
+   *
+   *              Only description.
+   */
+  description: string;
+}
+
+console.log(JSON.stringify(typia.json.application<[Something]>(), null, 2));

debug/package.json

@@ -15,6 +15,6 @@
     "typescript": "^5.4.2"
   },
   "dependencies": {
-    "typia": "../typia-6.1.0.tgz"
+    "typia": "../typia-6.1.2-dev.20240620.tgz"
   }
 }

errors/package.json

@@ -32,6 +32,6 @@
     "typescript": "^5.3.2"
   },
   "dependencies": {
-    "typia": "../typia-6.1.1.tgz"
+    "typia": "../typia-6.1.2.tgz"
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "typia",
-  "version": "6.1.1",
+  "version": "6.1.2",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

packages/typescript-json/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-json",
-  "version": "6.1.1",
+  "version": "6.1.2",
   "description": "Superfast runtime validators with only one line",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -63,7 +63,7 @@
   },
   "homepage": "https://typia.io",
   "dependencies": {
-    "typia": "6.1.1"
+    "typia": "6.1.2"
   },
   "peerDependencies": {
     "typescript": ">=4.8.0 <5.6.0"

src/programmers/internal/application_description.ts

@@ -0,0 +1,12 @@
+import { IJsDocTagInfo } from "../../module";
+
+export const application_description = (props: {
+  description: string | null | undefined;
+  jsDocTags: IJsDocTagInfo[];
+}): string | undefined =>
+  props.jsDocTags
+    .find((tag) => tag.name === "description")
+    ?.text?.[0]?.text?.split("\r\n")
+    .join("\n") ??
+  props.description ??
+  undefined;

src/programmers/internal/application_v30_alias.ts

@@ -5,6 +5,7 @@ import { CommentFactory } from "../../factories/CommentFactory";
 import { IJsDocTagInfo } from "../../schemas/metadata/IJsDocTagInfo";
 import { MetadataAlias } from "../../schemas/metadata/MetadataAlias";
 
+import { application_description } from "./application_description";
 import { application_v30_object } from "./application_v30_object";
 import { application_v30_schema } from "./application_v30_schema";
 
@@ -43,7 +44,7 @@ export const application_v30_alias =
             ? CommentFactory.merge(info.text)
             : undefined;
         })(),
-        description: alias.description ?? undefined,
+        description: application_description(alias),
       })(alias.value);
       if (schema !== null) Object.assign(components.schemas[key]!, schema);
     }

src/programmers/internal/application_v30_object.ts

@@ -8,6 +8,7 @@ import { MetadataObject } from "../../schemas/metadata/MetadataObject";
 
 import { PatternUtil } from "../../utils/PatternUtil";
 
+import { application_description } from "./application_description";
 import { application_v30_schema } from "./application_v30_schema";
 import { metadata_to_pattern } from "./metadata_to_pattern";
 
@@ -85,7 +86,7 @@ const create_object_schema =
             ? top.substring(0, top.length - 1)
             : undefined;
         })(),
-        description: property.description ?? undefined,
+        description: application_description(property),
       })(property.value);
 
       if (schema === null) continue;
@@ -111,7 +112,7 @@ const create_object_schema =
         );
         return info?.text?.length ? CommentFactory.merge(info.text) : undefined;
       })(),
-      description: obj.description,
+      description: application_description(obj),
       additionalProperties: join(components)(extraMeta),
     };
   };

src/programmers/internal/application_v31_alias.ts

@@ -5,6 +5,7 @@ import { CommentFactory } from "../../factories/CommentFactory";
 import { IJsDocTagInfo } from "../../schemas/metadata/IJsDocTagInfo";
 import { MetadataAlias } from "../../schemas/metadata/MetadataAlias";
 
+import { application_description } from "./application_description";
 import { application_v31_object } from "./application_v31_object";
 import { application_v31_schema } from "./application_v31_schema";
 
@@ -40,7 +41,7 @@ export const application_v31_alias =
             ? CommentFactory.merge(info.text)
             : undefined;
         })(),
-        description: alias.description ?? undefined,
+        description: application_description(alias),
       })(alias.value);
       if (schema !== null)
         Object.assign(components.schemas[alias.name]!, schema);

src/programmers/internal/application_v31_object.ts

@@ -8,6 +8,7 @@ import { MetadataObject } from "../../schemas/metadata/MetadataObject";
 
 import { PatternUtil } from "../../utils/PatternUtil";
 
+import { application_description } from "./application_description";
 import { application_v31_schema } from "./application_v31_schema";
 import { metadata_to_pattern } from "./metadata_to_pattern";
 
@@ -83,7 +84,7 @@ const create_object_schema =
             ? top.substring(0, top.length - 1)
             : undefined;
         })(),
-        description: property.description ?? undefined,
+        description: application_description(property),
       })(property.value);
 
       if (schema === null) continue;
@@ -108,7 +109,7 @@ const create_object_schema =
         );
         return info?.text?.length ? CommentFactory.merge(info.text) : undefined;
       })(),
-      description: obj.description,
+      description: application_description(obj),
       additionalProperties: join(components)(extraMeta),
     };
   };

test-esm/package.json

@@ -36,6 +36,6 @@
     "typescript": "^5.4.5"
   },
   "dependencies": {
-    "typia": "../typia-6.1.1.tgz"
+    "typia": "../typia-6.1.2.tgz"
   }
 }

test/package.json

@@ -51,6 +51,6 @@
     "suppress-warnings": "^1.0.2",
     "tstl": "^3.0.0",
     "uuid": "^9.0.1",
-    "typia": "../typia-6.1.1.tgz"
+    "typia": "../typia-6.1.2.tgz"
   }
 }

test/src/features/issues/test_issue_1100_json_description.ts

@@ -0,0 +1,90 @@
+import { OpenApi } from "@samchon/openapi";
+import typia, { IJsonApplication } from "typia";
+
+import { TestValidator } from "../../helpers/TestValidator";
+
+export const test_issue_1100_json_description = (): void => {
+  const v30 = typia.json.application<[Something], "3.0">();
+  const v31 = typia.json.application<[Something], "3.1">();
+
+  validate(v30);
+  validate(v31);
+};
+
+const validate = (
+  app: IJsonApplication.IV3_0 | IJsonApplication.IV3_1,
+): void => {
+  const something: OpenApi.IJsonSchema.IObject = (app.components.schemas as any)
+    .Something;
+  const id: OpenApi.IJsonSchema.IString = something.properties
+    ?.id as OpenApi.IJsonSchema.IString;
+  const name: OpenApi.IJsonSchema.IString = something.properties
+    ?.name as OpenApi.IJsonSchema.IString;
+  const description: OpenApi.IJsonSchema.IString = something.properties
+    ?.description as OpenApi.IJsonSchema.IString;
+
+  TestValidator.equals("Something.description")({
+    title: something.title,
+    description: something.description,
+  })({
+    title: "Something DTO",
+    description: [
+      "This is a description of the Something DTO.",
+      "Let's fill the content of it.",
+    ].join("\n\n"),
+  });
+  TestValidator.equals("Something.properties.id")({
+    title: id.title,
+    description: id.description,
+  })({
+    title: "This is the title",
+    description: ["This is the title.", "This is the description."].join(
+      "\n\n",
+    ),
+  });
+  TestValidator.equals("Something.properties.name")({
+    title: name.title,
+    description: name.description,
+  })({
+    title: "Name",
+    description: "This is the description of the name",
+  });
+  TestValidator.equals("Something.properties.description")({
+    title: description.title,
+    description: description.description,
+  })({
+    title: undefined,
+    description: ["No title.", "Only description."].join("\n\n"),
+  });
+};
+
+/**
+ * @title Something DTO
+ * @description This is a description of the Something DTO.
+ *
+ *              Let's fill the content of it.
+ * @author Samchon
+ */
+interface Something {
+  /**
+   * This is the title.
+   *
+   * This is the description.
+   */
+  id: string;
+
+  /**
+   * This is not the description.
+   *
+   * @title Name
+   * @description This is the description of the name
+   */
+  name: string;
+
+  /**
+   * @description No title.
+   *
+   *              Only description.
+   */
+  description: string;
+}

website/package.json

@@ -34,10 +34,10 @@
     "prettier": "^3.2.5",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "tgrid": "^1.0.0",
+    "tgrid": "^1.0.1",
     "tstl": "^3.0.0",
     "typescript": "^5.4.5",
-    "typia": "^6.1.1"
+    "typia": "^6.1.2"
   },
   "devDependencies": {
     "@trivago/prettier-plugin-sort-imports": "^4.3.0",