Merge pull request #663 from samchon/features/docs

Documentation for v2.3 update
samchon · Oct 18, 2023 · d6aa14d · d6aa14d
2 parents 3911c62 + c2751c3
commit d6aa14d
Show file tree

Hide file tree

Showing 10 changed files with 437 additions and 139 deletions.
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "2.3.0-dev.20231018",
+  "version": "2.3.0-dev.20231019",
   "description": "Super-fast validation decorators of NestJS",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -34,7 +34,7 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^2.3.0-dev.20231018",
+    "@nestia/fetcher": "^2.3.0-dev.20231019",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "@nestjs/platform-express": ">=7.0.1",
@@ -47,7 +47,7 @@
     "typia": "^5.2.2"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=2.3.0-dev.20231018",
+    "@nestia/fetcher": ">=2.3.0-dev.20231019",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "@nestjs/platform-express": ">=7.0.1",

diff --git a/packages/fetcher/package.json b/packages/fetcher/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nestia/fetcher",
-  "version": "2.3.0-dev.20231018",
+  "version": "2.3.0-dev.20231019",
   "description": "Fetcher library of Nestia SDK",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",

diff --git a/packages/sdk/assets/config/nestia.config.ts b/packages/sdk/assets/config/nestia.config.ts
@@ -18,18 +18,16 @@ export const NESTIA_CONFIG: INestiaConfig = {
         })
         class MyModule {}
         const app = await NestFactory.create(MyModule);
+        // app.setGlobalPrefix("api");
+        // app.enableVersioning({
+        //     type: VersioningType.URI,
+        //     prefix: "v",
+        // })
         return app;
     },
     // input: "src/controllers",
     // input: "src/**/*.controller.ts",
 
-    /**
-     * Output directory that SDK would be placed in.
-     *
-     * If not configured, you can't build the SDK library.
-     */
-    output: "src/api",
-
     /**
      * Building `swagger.json` is also possible.
      *
@@ -46,6 +44,13 @@ export const NESTIA_CONFIG: INestiaConfig = {
         output: "dist/swagger.json",
     },
 
+    /**
+     * Output directory that SDK would be placed in.
+     *
+     * If not configured, you can't build the SDK library.
+     */
+    output: "src/api",
+
     /**
      * Target directory that SDK distribution files would be placed in.
      *

diff --git a/packages/sdk/package.json b/packages/sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "2.3.0-dev.20231018",
+  "version": "2.3.0-dev.20231019",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -35,7 +35,7 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^2.3.0-dev.20231018",
+    "@nestia/fetcher": "^2.3.0-dev.20231019",
     "cli": "^1.0.1",
     "get-function-location": "^2.0.0",
     "glob": "^7.2.0",
@@ -48,7 +48,7 @@
     "typia": "^5.2.2"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=2.3.0-dev.20231018",
+    "@nestia/fetcher": ">=2.3.0-dev.20231019",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",

diff --git a/packages/sdk/src/INestiaConfig.ts b/packages/sdk/src/INestiaConfig.ts
@@ -11,26 +11,26 @@ import type { ISwaggerSecurityScheme } from "./structures/ISwaggerSecurityScheme
  * @author Jeongho Nam - https://github.com/samchon
  */
 export interface INestiaConfig {
-    /**
-     * Building `swagger.json` is also possible.
-     *
-     * If not specified, you can't build the `swagger.json`.
-     */
-    swagger?: INestiaConfig.ISwaggerConfig;
-
     /**
      * Accessor of controller classes.
      *
-     * You can specify it within two ways
+     * You can specify target controller classes within two ways
      *
      *   - Asynchronous function returning `INestApplication` instance
      *   - Specify the path or directory of controller class files
      */
     input:
-        | string
-        | string[]
+        | (() => Promise<INestApplication>)
         | INestiaConfig.IInput
-        | (() => Promise<INestApplication>);
+        | string[]
+        | string;
+
+    /**
+     * Building `swagger.json` is also possible.
+     *
+     * If not specified, you can't build the `swagger.json`.
+     */
+    swagger?: INestiaConfig.ISwaggerConfig;
 
     /**
      * Output directory that SDK would be placed in.

diff --git a/test/package.json b/test/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@nestia/test",
-  "version": "2.3.0-dev.20231018",
+  "version": "2.3.0-dev.20231019",
   "description": "Test program of Nestia",
   "main": "index.js",
   "scripts": {
@@ -37,9 +37,9 @@
     "typia": "^5.2.2",
     "uuid": "^9.0.0",
     "nestia": "^4.5.0",
-    "@nestia/core": "^2.3.0-dev.20231018",
+    "@nestia/core": "^2.3.0-dev.20231019",
     "@nestia/e2e": "^0.3.6",
-    "@nestia/fetcher": "^2.3.0-dev.20231018",
-    "@nestia/sdk": "^2.3.0-dev.20231018"
+    "@nestia/fetcher": "^2.3.0-dev.20231019",
+    "@nestia/sdk": "^2.3.0-dev.20231019"
   }
 }
diff --git a/website/pages/docs/sdk/e2e.mdx b/website/pages/docs/sdk/e2e.mdx
@@ -3,21 +3,33 @@ import { Tabs, Tab } from 'nextra-theme-docs'
 ## Outline
 <Tabs items={['Configuration', 'Build Script']} defaultIndex={1}>
     <Tab>
-```typescript filename="nestia.config.ts" copy showLineNumbers {7}
+```typescript filename="nestia.config.ts" copy showLineNumbers {18}
 import { INestiaConfig } from "@nestia/sdk";
+import { NestFactory } from "@nestjs/core";
 
-const config: INestiaConfig = {
-    input: "src/controllers",
+import { YourModule } from "./src/YourModule";
+
+const NESTIA_CONFIG: INestiaConfig = {
+    input: async () => {
+        const app = await NestFactory.create(YourModule);
+        // app.setGlobalPrefix("api");
+        // app.enableVersioning({
+        //     type: VersioningType.URI,
+        //     prefix: "v", 
+        // })
+        return app;
+    },
     output: "src/api",
     distribute: "packages/api",
     e2e: "test",
 };
-export default config;
+export default NESTIA_CONFIG;
 ```
     </Tab>
     <Tab>
 ```bash filename="Terminal" copy showLineNumbers
 npx nestia e2e
+npx nestia e2e --config another.config.ts
 ```
     </Tab>
 </Tabs>
@@ -58,20 +70,33 @@ export const test_api_body_store = async (
     <code>INestiaConfig.ts</code>
 ]}>
     <Tab>
-```typescript copy filename="nestia.config.ts" showLineNumbers {7}
+```typescript copy filename="nestia.config.ts" showLineNumbers {18}
 import { INestiaConfig } from "@nestia/sdk";
+import { NestFactory } from "@nestjs/core";
 
-const config: INestiaConfig = {
-    input: "src/controllers",
+import { YourModule } from "./src/YourModule";
+
+const NESTIA_CONFIG: INestiaConfig = {
+    input: async () => {
+        const app = await NestFactory.create(YourModule);
+        // app.setGlobalPrefix("api");
+        // app.enableVersioning({
+        //     type: VersioningType.URI,
+        //     prefix: "v", 
+        // })
+        return app;
+    },
     output: "src/api",
     distribute: "packages/api",
     e2e: "test",
 };
-export default config;
+export default NESTIA_CONFIG;
 ```
     </Tab>
     <Tab>
-```typescript filename="INestiaConfig.ts" showLineNumbers {18-28, 59-68}
+```typescript copy filename="INestiaConfig.ts" showLineNumbers {70-79}
+import type { INestApplication } from "@nestjs/common";
+
 import type { ISwagger } from "./structures/ISwagger";
 import type { ISwaggerInfo } from "./structures/ISwaggerInfo";
 import type { ISwaggerSecurityScheme } from "./structures/ISwaggerSecurityScheme";
@@ -83,16 +108,18 @@ import type { ISwaggerSecurityScheme } from "./structures/ISwaggerSecurityScheme
  */
 export interface INestiaConfig {
     /**
-     * Building `swagger.json` is also possible.
+     * Accessor of controller classes.
      *
-     * If not specified, you can't build the `swagger.json`.
-     */
-    swagger?: INestiaConfig.ISwaggerConfig;
-
-    /**
-     * List of files or directories containing the NestJS controller classes.
+     * You can specify it within two ways
+     *
+     *   - Asynchronous function returning `INestApplication` instance
+     *   - Specify the path or directory of controller class files
      */
-    input: string | string[] | INestiaConfig.IInput;
+    input:
+        | (() => Promise<INestApplication>)
+        | INestiaConfig.IInput
+        | string[]
+        | string;
 
     /**
      * Output directory that SDK would be placed in.
@@ -101,6 +128,13 @@ export interface INestiaConfig {
      */
     output?: string;
 
+    /**
+     * Building `swagger.json` is also possible.
+     *
+     * If not specified, you can't build the `swagger.json`.
+     */
+    swagger?: INestiaConfig.ISwaggerConfig;
+
     /**
      * Target directory that SDK distribution files would be placed in.
      *
@@ -297,20 +331,50 @@ At first, create `nestia.config.ts` file through `npx nestia init` command. It w
 
 At least, you've to configure those three properties:
 
-  - `input`: Path of controller files
+  - `input`: Accessor of controller classes
   - `output`: Path of output directory for SDK library
   - `e2e`: Path of output directory for E2E test functions
 
 When you've completed above configuration, just run `npx nestia e2e` command. Then, [SDK library](./sdk) would be generated into the `$config.output` directory, and E2E test functions would be generated into the `$config.e2e` directory, following your `nestia.config.ts` option.
 
-By the way, if your controller files are separated into multiple directories, you can choose two options. First is listing up every directories, and second is using regex expression. Also, you can exclude some special directories or files using `exclude` option. Of course, you can mix all of these options like below:
+By the way, `nestia.config.ts` supports alternative options specifying the target controller classes instead of using the `Module` instance. If your backend application server does not have special configuration like `setGlobalPrefix`, `enableVersioning` and `RouterModule`, it is okay to specifying the target controller classes just by writing their file path like below.
+
+<Tabs items={[
+        'Module',
+        'Directory', 
+        'Pattern', 
+        'Exclude'
+    ]}
+    defaultIndex={1}>
+    <Tab>
+```typescript copy filename="nestia.config.ts" showLineNumbers {7-15}
+import { INestiaConfig } from "@nestia/sdk";
+import { NestFactory } from "@nestjs/core";
 
-<Tabs items={['List up every directories', 'Use regex pattern', 'Exclude']} defaultIndex={2}>
+import { YourModule } from "./src/YourModule";
+
+const NESTIA_CONFIG: INestiaConfig = {
+    input: async () => {
+        const app = await NestFactory.create(YourModule);
+        // app.setGlobalPrefix("api");
+        // app.enableVersioning({
+        //     type: VersioningType.URI,
+        //     prefix: "v", 
+        // })
+        return app;
+    },
+    output: "src/api",
+    distribute: "packages/api",
+    e2e: "test",
+};
+export default NESTIA_CONFIG;
+```
+    </Tab>
     <Tab>
 ```typescript copy filename="nestia.config.ts" showLineNumbers {4-8}
 import { INestiaConfig } from "@nestia/sdk";
 
-const config: INestiaConfig = {
+const NESTIA_CONFIG: INestiaConfig = {
     input: [
         "src/controllers", 
         "src/fake/controllers", 
@@ -320,27 +384,27 @@ const config: INestiaConfig = {
     distribute: "packages/api",
     e2e: "test",
 };
-export default config;
+export default NESTIA_CONFIG;
 ```
     </Tab>
     <Tab>
 ```typescript copy filename="nestia.config.ts" showLineNumbers {4}
 import { INestiaConfig } from "@nestia/sdk";
 
-const config: INestiaConfig = {
+const NESTIA_CONFIG: INestiaConfig = {
     input: "src/**/*.controller.ts",
     output: "src/api",
     distribute: "packages/api",
     e2e: "test",
 };
-export default config;
+export default NESTIA_CONFIG;
 ```
     </Tab>
     <Tab>
 ```typescript copy filename="nestia.config.ts" showLineNumbers {4-7}
 import { INestiaConfig } from "@nestia/sdk";
 
-const config: INestiaConfig = {
+const NESTIA_CONFIG: INestiaConfig = {
     input: {
         include: ["src/controllers"],
         exclude: ["src/**/*.fake.ts"],
@@ -349,7 +413,7 @@ const config: INestiaConfig = {
     distribute: "packages/api",
     e2e: "test",
 };
-export default config;
+export default NESTIA_CONFIG;
 ```
     </Tab>
 </Tabs>