Merge pull request #858 from samchon/features/tags

Support swagger tag description

package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@nestia/station",
-  "version": "2.6.3",
+  "version": "2.6.4",
   "description": "Nestia station",
   "main": "prettier.config.js",
   "scripts": {

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "2.6.3",
+  "version": "2.6.4",
   "description": "Super-fast validation decorators of NestJS",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -36,7 +36,7 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^2.6.3",
+    "@nestia/fetcher": "^2.6.4",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "detect-ts-node": "^1.0.5",
@@ -48,7 +48,7 @@
     "typia": "^5.5.7"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=2.6.3",
+    "@nestia/fetcher": ">=2.6.4",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",

packages/fetcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/fetcher",
-  "version": "2.6.3",
+  "version": "2.6.4",
   "description": "Fetcher library of Nestia SDK",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "2.6.3",
+  "version": "2.6.4",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -32,7 +32,7 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^2.6.3",
+    "@nestia/fetcher": "^2.6.4",
     "cli": "^1.0.1",
     "get-function-location": "^2.0.0",
     "glob": "^7.2.0",
@@ -45,7 +45,7 @@
     "typia": "^5.5.7"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=2.6.3",
+    "@nestia/fetcher": ">=2.6.4",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",

packages/sdk/src/INestiaConfig.ts

@@ -1,9 +1,10 @@
 import type { INestApplication } from "@nestjs/common";
 
 import type { INormalizedInput } from "./structures/INormalizedInput";
-import type { ISwagger } from "./structures/ISwagger";
 import type { ISwaggerInfo } from "./structures/ISwaggerInfo";
 import type { ISwaggerSecurityScheme } from "./structures/ISwaggerSecurityScheme";
+import type { ISwaggerServer } from "./structures/ISwaggerServer";
+import type { ISwaggerTag } from "./structures/ISwaggerTag";
 
 /**
  * Definition for the `nestia.config.ts` file.
@@ -217,7 +218,7 @@ export namespace INestiaConfig {
     /**
      * List of server addresses.
      */
-    servers?: ISwagger.IServer[];
+    servers?: ISwaggerServer[];
 
     /**
      * Security schemes.
@@ -228,6 +229,18 @@ export namespace INestiaConfig {
      */
     security?: Record<string, ISwaggerSecurityScheme>;
 
+    /**
+     * List of tag names with description.
+     *
+     * It is possible to omit this property or skip some tag name even if
+     * the tag name is used in the API routes. In that case, the tag name
+     * would be used without description.
+     *
+     * Of course, if you've written a comment like `@tag {name} {descrition}`,
+     * you can entirely replace this property specification.
+     */
+    tags?: ISwaggerTag[];
+
     /**
      * Decompose query DTO.
      *

packages/sdk/src/generates/SwaggerGenerator.ts

@@ -27,6 +27,7 @@ export namespace SwaggerGenerator {
     lazySchemas: Array<ISwaggerLazySchema>;
     lazyProperties: Array<ISwaggerLazyProperty>;
     errors: ISwaggerError[];
+    swagger: ISwagger;
   }
 
   export const generate =
@@ -80,6 +81,7 @@ export namespace SwaggerGenerator {
           lazySchemas,
           lazyProperties,
           errors,
+          swagger,
         })(route);
       }
       swagger.paths = {};
@@ -329,6 +331,7 @@ export namespace SwaggerGenerator {
       },
       paths: {},
       components: {},
+      tags: config.tags ?? [],
     };
   };
 
@@ -344,8 +347,11 @@ export namespace SwaggerGenerator {
   const generate_route =
     (props: IProps) =>
     (route: IRoute): ISwaggerRoute => {
+      // FIND REQUEST BODY
       const body = route.parameters.find((param) => param.category === "body");
-      const getJsDocTexts = (name: string) =>
+
+      // CONSTRUCT SUMMARY & DESCRIPTION
+      const getJsDocTexts = (name: string): string[] =>
         route.jsDocTags
           .filter(
             (tag) =>
@@ -356,7 +362,6 @@ export namespace SwaggerGenerator {
               ) !== undefined,
           )
           .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);
-
       const description: string | undefined = route.description?.length
         ? route.description
         : undefined;
@@ -376,9 +381,25 @@ export namespace SwaggerGenerator {
         (tag) => tag.name === "deprecated",
       );
 
+      // CONSTRUCT TAGS
+      const tagSet: Set<string> = new Set([
+        ...route.swaggerTags,
+        ...getJsDocTexts("tag").map((tag) => tag.split(" ")[0]),
+      ]);
+      for (const tag of tagSet)
+        if (props.swagger.tags.find((elem) => elem.name === tag) === undefined)
+          props.swagger.tags.push({ name: tag });
+      for (const texts of getJsDocTexts("tag")) {
+        const [name, ...description] = texts.split(" ");
+        if (description.length)
+          props.swagger.tags.find((elem) => elem.name === name)!.description ??=
+            description.join(" ");
+      }
+
+      // FINALIZE
       return {
         deprecated: deprecated ? true : undefined,
-        tags: [...route.swaggerTags, ...new Set([...getJsDocTexts("tag")])],
+        tags: [...tagSet],
         operationId:
           route.operationId ??
           props.config.operationId?.({

packages/sdk/src/structures/ISwagger.ts

@@ -1,6 +1,8 @@
 import { ISwaggerComponents } from "./ISwaggerComponents";
 import { ISwaggerInfo } from "./ISwaggerInfo";
 import { ISwaggerRoute } from "./ISwaggerRoute";
+import { ISwaggerServer } from "./ISwaggerServer";
+import { ISwaggerTag } from "./ISwaggerTag";
 
 /**
  * Swagger Document.
@@ -22,7 +24,7 @@ export interface ISwagger {
   /**
    * List of servers that provide the API.
    */
-  servers: ISwagger.IServer[];
+  servers: ISwaggerServer[];
 
   /**
    * Information about the API.
@@ -46,6 +48,11 @@ export interface ISwagger {
    */
   components: ISwaggerComponents;
 
+  /**
+   * List of tags.
+   */
+  tags: ISwaggerTag[];
+
   // /**
   //  * A declaration of which security mechanisms can be used across the API.
   //  *
@@ -57,35 +64,3 @@ export interface ISwagger {
   //  */
   // security?: Record<string, string[]>[];
 }
-export namespace ISwagger {
-  /**
-   * Remote server definition.
-   */
-  export interface IServer {
-    /**
-     * A URL to the target host.
-     *
-     * @format uri
-     */
-    url: string;
-
-    /**
-     * An optional string describing the target server.
-     */
-    description?: string;
-  }
-
-  export interface IExternalDocs {
-    /**
-     * The URL for target documentation.
-     *
-     * @format uri
-     */
-    url: string;
-
-    /**
-     * A short description of the target documentation.
-     */
-    description?: string;
-  }
-}

packages/sdk/src/structures/ISwaggerServer.ts

@@ -0,0 +1,16 @@
+/**
+ * Remote server definition.
+ */
+export interface ISwaggerServer {
+  /**
+   * A URL to the target host.
+   *
+   * @format uri
+   */
+  url: string;
+
+  /**
+   * An optional string describing the target server.
+   */
+  description?: string;
+}

packages/sdk/src/structures/ISwaggerTag.ts

@@ -0,0 +1,9 @@
+/**
+ * Tag name and description.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ISwaggerTag {
+  name: string;
+  description?: string;
+}

test/features/tags/nestia.config.ts

@@ -6,6 +6,7 @@ export const NESTIA_CONFIG: INestiaConfig = {
   e2e: "src/test",
   swagger: {
     output: "swagger.json",
+    beautify: true,
   },
 };
 export default NESTIA_CONFIG;

test/features/tags/src/api/functional/bbs/articles/index.ts

@@ -13,7 +13,7 @@ import type { IBbsArticle } from "../../../structures/IBbsArticle";
 /**
  * Would be shown without any mark.
  *
- * @tag public
+ * @tag public Some description describing public group...
  * @summary Public API
  * @param section Section code
  * @param input Content to store

test/features/tags/src/controllers/BbsArticlesController.ts

@@ -11,7 +11,7 @@ export class BbsArticlesController {
   /**
    * Would be shown without any mark.
    *
-   * @tag public
+   * @tag public Some description describing public group...
    * @summary Public API
    * @param section Section code
    * @param input Content to store