Merge pull request #291 from samchon/features/tags

Support `@internal` and @deprecated` tags (SDK)
samchon · Mar 29, 2023 · 6322445 · 6322445
2 parents a6196d8 + 6f4ead8
commit 6322445
Show file tree

Hide file tree

Showing 10 changed files with 60 additions and 74 deletions.
diff --git a/packages/sdk/demo/176/src/api/functional/userspace/index.ts b/packages/sdk/demo/176/src/api/functional/userspace/index.ts
@@ -10,6 +10,11 @@ import type { IConnection } from "@nestia/fetcher";
 import type { Userspace } from "./../../structures/Userspace";
 
 /**
+ * Type one.
+ * 
+ * @returns something
+ * @deprecated
+ * 
  * @controller UserspaceController.type1()
  * @path GET /userspace/type1
  * @nestia Generated by Nestia - https://github.com/samchon/nestia
@@ -45,6 +50,8 @@ export namespace type1
 }
 
 /**
+ * @internal
+ * 
  * @controller UserspaceController.type2()
  * @path GET /userspace/type2
  * @nestia Generated by Nestia - https://github.com/samchon/nestia

diff --git a/packages/sdk/demo/176/src/controllers/UserspaceController.ts b/packages/sdk/demo/176/src/controllers/UserspaceController.ts
@@ -5,13 +5,22 @@ import { Userspace } from "../api/structures/Userspace";
 
 @nest.Controller("userspace")
 export class UserspaceController {
+    /**
+     * Type one.
+     *
+     * @returns something
+     * @deprecated
+     */
     @core.TypedRoute.Get("type1")
     public async type1(): Promise<Userspace.UserType1> {
         return {
             id: "some-id",
         };
     }
 
+    /**
+     * @internal
+     */
     @nest.Get("type2")
     public async type2(): Promise<Userspace.UserType2> {
         return {

diff --git a/packages/sdk/demo/176/swagger.json b/packages/sdk/demo/176/swagger.json
@@ -17,7 +17,7 @@
         "parameters": [],
         "responses": {
           "200": {
-            "description": "",
+            "description": "something",
             "content": {
               "application/json": {
                 "schema": {
@@ -28,31 +28,23 @@
             "x-nestia-encrypted": false
           }
         },
-        "description": "",
+        "summary": "Type one",
+        "description": "Type one.",
         "x-nestia-namespace": "userspace.type1.type1",
-        "x-nestia-jsDocTags": []
-      }
-    },
-    "/userspace/type2": {
-      "get": {
-        "tags": [],
-        "parameters": [],
-        "responses": {
-          "200": {
-            "description": "",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Userspace.UserType2"
-                }
+        "x-nestia-jsDocTags": [
+          {
+            "name": "returns",
+            "text": [
+              {
+                "text": "something",
+                "kind": "text"
               }
-            },
-            "x-nestia-encrypted": false
+            ]
+          },
+          {
+            "name": "deprecated"
           }
-        },
-        "description": "",
-        "x-nestia-namespace": "userspace.type2.type2",
-        "x-nestia-jsDocTags": []
+        ]
       }
     }
   },
@@ -72,27 +64,6 @@
           "id"
         ],
         "x-typia-jsDocTags": []
-      },
-      "Userspace.UserType2": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "string",
-            "nullable": false,
-            "x-typia-required": true
-          },
-          "name": {
-            "type": "string",
-            "nullable": false,
-            "x-typia-required": true
-          }
-        },
-        "nullable": false,
-        "required": [
-          "id",
-          "name"
-        ],
-        "x-typia-jsDocTags": []
       }
     }
   }

diff --git a/...ges/sdk/demo/multiple-paths/src/api/functional/consumers/sales/articles/comments/index.ts b/...ges/sdk/demo/multiple-paths/src/api/functional/consumers/sales/articles/comments/index.ts
@@ -19,10 +19,10 @@ import type { ISaleArticleComment } from "./../../../../../structures/ISaleArtic
  * @param articleId ID of the target article
  * @param input Content to write
  * @return Newly archived comment
- * @throw 400 bad request error when type of the input data is not valid
- * @throw 401 unauthorized error when you've not logged in yet
- * @throw 403 forbidden error when you're a seller and the sale is not yours
- * @throw 404 not found error when unable to find the matched record
+ * @throws 400 bad request error when type of the input data is not valid
+ * @throws 401 unauthorized error when you've not logged in yet
+ * @throws 403 forbidden error when you're a seller and the sale is not yours
+ * @throws 404 not found error when unable to find the matched record
  * 
  * @controller MultipleCommentsController.store()
  * @path POST /consumers/:section/sales/:saleId/articles/:articleId/comments

diff --git a/packages/sdk/demo/multiple-paths/src/api/functional/sellers/sales/articles/comments/index.ts b/packages/sdk/demo/multiple-paths/src/api/functional/sellers/sales/articles/comments/index.ts
@@ -19,10 +19,10 @@ import type { ISaleArticleComment } from "./../../../../../structures/ISaleArtic
  * @param articleId ID of the target article
  * @param input Content to write
  * @return Newly archived comment
- * @throw 400 bad request error when type of the input data is not valid
- * @throw 401 unauthorized error when you've not logged in yet
- * @throw 403 forbidden error when you're a seller and the sale is not yours
- * @throw 404 not found error when unable to find the matched record
+ * @throws 400 bad request error when type of the input data is not valid
+ * @throws 401 unauthorized error when you've not logged in yet
+ * @throws 403 forbidden error when you're a seller and the sale is not yours
+ * @throws 404 not found error when unable to find the matched record
  * 
  * @controller MultipleCommentsController.store()
  * @path POST /sellers/:section/sales/:saleId/articles/:articleId/comments

diff --git a/packages/sdk/demo/multiple-paths/src/controllers/MultipleController.ts b/packages/sdk/demo/multiple-paths/src/controllers/MultipleController.ts
@@ -21,10 +21,10 @@ export class MultipleCommentsController {
      * @param input Content to write
      * @return Newly archived comment
      *
-     * @throw 400 bad request error when type of the input data is not valid
-     * @throw 401 unauthorized error when you've not logged in yet
-     * @throw 403 forbidden error when you're a seller and the sale is not yours
-     * @throw 404 not found error when unable to find the matched record
+     * @throws 400 bad request error when type of the input data is not valid
+     * @throws 401 unauthorized error when you've not logged in yet
+     * @throws 403 forbidden error when you're a seller and the sale is not yours
+     * @throws 404 not found error when unable to find the matched record
      */
     @nest.Post([])
     public async store(

diff --git a/packages/sdk/demo/multiple-paths/swagger.json b/packages/sdk/demo/multiple-paths/swagger.json
@@ -242,7 +242,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "400 bad request error when type of the input data is not valid",
@@ -251,7 +251,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "401 unauthorized error when you've not logged in yet",
@@ -260,7 +260,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "403 forbidden error when you're a seller and the sale is not yours",
@@ -269,7 +269,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "404 not found error when unable to find the matched record",
@@ -451,7 +451,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "400 bad request error when type of the input data is not valid",
@@ -460,7 +460,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "401 unauthorized error when you've not logged in yet",
@@ -469,7 +469,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "403 forbidden error when you're a seller and the sale is not yours",
@@ -478,7 +478,7 @@
             ]
           },
           {
-            "name": "throw",
+            "name": "throws",
             "text": [
               {
                 "text": "404 not found error when unable to find the matched record",

diff --git a/packages/sdk/package.json b/packages/sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

diff --git a/packages/sdk/src/generates/FunctionGenerator.ts b/packages/sdk/src/generates/FunctionGenerator.ts
@@ -136,9 +136,7 @@ export namespace FunctionGenerator {
         if (comments.length) comments.push("");
 
         // FILTER TAGS (VULNERABLE PARAMETERS WOULD BE REMOVED)
-        const tagList: ts.JSDocTagInfo[] = route.tags.filter(
-            (tag) => tag.text !== undefined,
-        );
+        const tagList: ts.JSDocTagInfo[] = route.tags.slice();
         if (tagList.length !== 0) {
             const index: number = tagList.findIndex((t) => t.name === "param");
             if (index !== -1) {
@@ -162,11 +160,12 @@ export namespace FunctionGenerator {
                 });
             }
             comments.push(
-                ...tagList.map(
-                    (tag) =>
-                        `@${tag.name} ${tag
-                            .text!.map((elem) => elem.text)
-                            .join("")}`,
+                ...tagList.map((tag) =>
+                    tag.text
+                        ? `@${tag.name} ${tag.text
+                              .map((elem) => elem.text)
+                              .join("")}`
+                        : `@${tag.name}`,
                 ),
                 "",
             );

diff --git a/packages/sdk/src/generates/SwaggerGenerator.ts b/packages/sdk/src/generates/SwaggerGenerator.ts
@@ -329,7 +329,7 @@ export namespace SwaggerGenerator {
             route.tags
                 .filter(
                     (tag) =>
-                        tag.name === "throw" &&
+                        (tag.name === "throw" || tag.name === "throws") &&
                         tag.text &&
                         tag.text.find(
                             (elem) =>