Close #880: support multiple openapi versions generation.

package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@nestia/station",
-  "version": "3.6.1",
+  "version": "3.7.0-dev.20240711",
   "description": "Nestia station",
   "scripts": {
     "build": "node build/index.js",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/core",
-  "version": "3.6.1",
+  "version": "3.7.0-dev.20240711",
   "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": "^3.6.1",
+    "@nestia/fetcher": "^3.7.0-dev.20240711",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "@samchon/openapi": "^0.3.4",
@@ -53,7 +53,7 @@
     "ws": "^7.5.3"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=3.6.1",
+    "@nestia/fetcher": ">=3.7.0-dev.20240711",
     "@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": "3.6.1",
+  "version": "3.7.0-dev.20240711",
   "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": "3.6.1",
+  "version": "3.7.0-dev.20240711",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -32,8 +32,8 @@
   },
   "homepage": "https://nestia.io",
   "dependencies": {
-    "@nestia/fetcher": "^3.6.1",
-    "@nestia/core": "^3.6.1",
+    "@nestia/fetcher": "^3.7.0-dev.20240711",
+    "@nestia/core": "^3.7.0-dev.20240711",
     "@samchon/openapi": "^0.3.4",
     "cli": "^1.0.1",
     "get-function-location": "^2.0.0",
@@ -47,8 +47,8 @@
     "typia": "^6.4.3"
   },
   "peerDependencies": {
-    "@nestia/fetcher": ">=3.6.1",
-    "@nestia/core": ">=3.6.1",
+    "@nestia/fetcher": ">=3.7.0-dev.20240711",
+    "@nestia/core": ">=3.7.0-dev.20240711",
     "@nestjs/common": ">=7.0.1",
     "@nestjs/core": ">=7.0.1",
     "reflect-metadata": ">=0.1.12",

packages/sdk/src/INestiaConfig.ts

@@ -173,6 +173,18 @@ export namespace INestiaConfig {
      */
     output: string;
 
+    /**
+     * OpenAPI version.
+     * 
+     * If you configure this property to be `2.0` or `3.0`, the newly generated
+     * `swagger.json` file would follow the specified OpenAPI version. The newly
+     * generated `swagger.json` file would be downgraded from the OpenAPI v3.1
+     * specification by {@link OpenApi.downgrade} method.
+     * 
+     * @default 3.1
+     */
+    openapi?: "2.0" | "3.0" | "3.1";
+
     /**
      * Whether to beautify JSON content or not.
      *

packages/sdk/src/generates/SwaggerGenerator.ts

@@ -1,4 +1,4 @@
-import { OpenApi } from "@samchon/openapi";
+import { OpenApi, OpenApiV3, SwaggerV2 } from "@samchon/openapi";
 import fs from "fs";
 import path from "path";
 import { Singleton } from "tstl";
@@ -208,12 +208,21 @@ export namespace SwaggerGenerator {
       }
 
       // DO GENERATE
+      const document:
+        | OpenApi.IDocument
+        | SwaggerV2.IDocument
+        | OpenApiV3.IDocument =
+        config.openapi === "2.0"
+          ? OpenApi.downgrade(swagger, config.openapi as "2.0")
+          : config.openapi === "3.0"
+            ? OpenApi.downgrade(swagger, config.openapi as "3.0")
+            : swagger;
       await fs.promises.writeFile(
         location,
         !config.beautify
-          ? JSON.stringify(swagger)
+          ? JSON.stringify(document)
           : JSON.stringify(
-              swagger,
+              document,
               null,
               typeof config.beautify === "number" ? config.beautify : 2,
             ),

test/features/openapi_v2/nestia.config.ts

@@ -0,0 +1,25 @@
+import { INestiaConfig } from "@nestia/sdk";
+import { INestApplication } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+
+import { ApplicationModule } from "./src/modules/ApplicationModule";
+
+export const NESTIA_CONFIG: INestiaConfig = {
+  input: async () => {
+    const app: INestApplication = await NestFactory.create(ApplicationModule, {
+      logger: false,
+    });
+    return app;
+  },
+  output: "src/api",
+  swagger: {
+    output: "swagger.json",
+    openapi: "2.0",
+    security: {
+      bearer: {
+        type: "apiKey",
+      },
+    },
+  },
+};
+export default NESTIA_CONFIG;

test/features/openapi_v2/src/Backend.ts

@@ -0,0 +1,20 @@
+import { INestApplication } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { Singleton } from "tstl";
+
+import { ApplicationModule } from "./modules/ApplicationModule";
+
+export class Backend {
+  public readonly application: Singleton<Promise<INestApplication>> =
+    new Singleton(() =>
+      NestFactory.create(ApplicationModule, { logger: false }),
+    );
+
+  public async open(): Promise<void> {
+    return (await this.application.get()).listen(37_000);
+  }
+
+  public async close(): Promise<void> {
+    return (await this.application.get()).close();
+  }
+}

test/features/openapi_v2/src/api/HttpError.ts

@@ -0,0 +1 @@
+export { HttpError } from "@nestia/fetcher";

test/features/openapi_v2/src/api/IConnection.ts

@@ -0,0 +1 @@
+export type { IConnection } from "@nestia/fetcher";

test/features/openapi_v2/src/api/Primitive.ts

@@ -0,0 +1 @@
+export type { Primitive } from "@nestia/fetcher";

test/features/openapi_v2/src/api/functional/articles/comments/index.ts

@@ -0,0 +1,204 @@
+/**
+ * @packageDocumentation
+ * @module api.functional.articles.comments
+ * @nestia Generated by Nestia - https://github.com/samchon/nestia
+ */
+//================================================================
+import type { IConnection, Resolved, Primitive } from "@nestia/fetcher";
+import { PlainFetcher } from "@nestia/fetcher/lib/PlainFetcher";
+import type { Format } from "typia/lib/tags/Format";
+
+import type { IBbsComment } from "../../../structures/IBbsComment";
+import type { IPage } from "../../../structures/IPage";
+
+/**
+ * @controller BbsCommentsController.index
+ * @path GET /:section/articles/:articleId/comments
+ * @nestia Generated by Nestia - https://github.com/samchon/nestia
+ */
+export async function index(
+  connection: IConnection,
+  section: string,
+  articleId: string & Format<"uuid">,
+  query: index.Query,
+): Promise<index.Output> {
+  return PlainFetcher.fetch(connection, {
+    ...index.METADATA,
+    template: index.METADATA.path,
+    path: index.path(section, articleId, query),
+  });
+}
+export namespace index {
+  export type Query = Resolved<IPage.IRequest>;
+  export type Output = Primitive<IPage<IBbsComment>>;
+
+  export const METADATA = {
+    method: "GET",
+    path: "/:section/articles/:articleId/comments",
+    request: null,
+    response: {
+      type: "application/json",
+      encrypted: false,
+    },
+    status: null,
+  } as const;
+
+  export const path = (
+    section: string,
+    articleId: string & Format<"uuid">,
+    query: index.Query,
+  ) => {
+    const variables: URLSearchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(query as any))
+      if (undefined === value) continue;
+      else if (Array.isArray(value))
+        value.forEach((elem: any) => variables.append(key, String(elem)));
+      else variables.set(key, String(value));
+    const location: string = `/${encodeURIComponent(section ?? "null")}/articles/${encodeURIComponent(articleId ?? "null")}/comments`;
+    return 0 === variables.size
+      ? location
+      : `${location}?${variables.toString()}`;
+  };
+}
+
+/**
+ * @controller BbsCommentsController.at
+ * @path GET /:section/articles/:articleId/comments/:id
+ * @nestia Generated by Nestia - https://github.com/samchon/nestia
+ */
+export async function at(
+  connection: IConnection,
+  section: string,
+  articleId: string & Format<"uuid">,
+  id: string & Format<"uuid">,
+): Promise<at.Output> {
+  return PlainFetcher.fetch(connection, {
+    ...at.METADATA,
+    template: at.METADATA.path,
+    path: at.path(section, articleId, id),
+  });
+}
+export namespace at {
+  export type Output = Primitive<IBbsComment>;
+
+  export const METADATA = {
+    method: "GET",
+    path: "/:section/articles/:articleId/comments/:id",
+    request: null,
+    response: {
+      type: "application/json",
+      encrypted: false,
+    },
+    status: null,
+  } as const;
+
+  export const path = (
+    section: string,
+    articleId: string & Format<"uuid">,
+    id: string & Format<"uuid">,
+  ) =>
+    `/${encodeURIComponent(section ?? "null")}/articles/${encodeURIComponent(articleId ?? "null")}/comments/${encodeURIComponent(id ?? "null")}`;
+}
+
+/**
+ * @controller BbsCommentsController.store
+ * @path POST /:section/articles/:articleId/comments
+ * @nestia Generated by Nestia - https://github.com/samchon/nestia
+ */
+export async function store(
+  connection: IConnection,
+  section: string,
+  articleId: string & Format<"uuid">,
+  input: store.Input,
+): Promise<store.Output> {
+  return PlainFetcher.fetch(
+    {
+      ...connection,
+      headers: {
+        ...connection.headers,
+        "Content-Type": "application/json",
+      },
+    },
+    {
+      ...store.METADATA,
+      template: store.METADATA.path,
+      path: store.path(section, articleId),
+    },
+    input,
+  );
+}
+export namespace store {
+  export type Input = Primitive<IBbsComment.IStore>;
+  export type Output = Primitive<IBbsComment>;
+
+  export const METADATA = {
+    method: "POST",
+    path: "/:section/articles/:articleId/comments",
+    request: {
+      type: "application/json",
+      encrypted: false,
+    },
+    response: {
+      type: "application/json",
+      encrypted: false,
+    },
+    status: null,
+  } as const;
+
+  export const path = (section: string, articleId: string & Format<"uuid">) =>
+    `/${encodeURIComponent(section ?? "null")}/articles/${encodeURIComponent(articleId ?? "null")}/comments`;
+}
+
+/**
+ * @controller BbsCommentsController.update
+ * @path PUT /:section/articles/:articleId/comments/:id
+ * @nestia Generated by Nestia - https://github.com/samchon/nestia
+ */
+export async function update(
+  connection: IConnection,
+  section: string,
+  articleId: string & Format<"uuid">,
+  id: string & Format<"uuid">,
+  input: update.Input,
+): Promise<update.Output> {
+  return PlainFetcher.fetch(
+    {
+      ...connection,
+      headers: {
+        ...connection.headers,
+        "Content-Type": "application/json",
+      },
+    },
+    {
+      ...update.METADATA,
+      template: update.METADATA.path,
+      path: update.path(section, articleId, id),
+    },
+    input,
+  );
+}
+export namespace update {
+  export type Input = Primitive<IBbsComment.IStore>;
+  export type Output = Primitive<IBbsComment>;
+
+  export const METADATA = {
+    method: "PUT",
+    path: "/:section/articles/:articleId/comments/:id",
+    request: {
+      type: "application/json",
+      encrypted: false,
+    },
+    response: {
+      type: "application/json",
+      encrypted: false,
+    },
+    status: null,
+  } as const;
+
+  export const path = (
+    section: string,
+    articleId: string & Format<"uuid">,
+    id: string & Format<"uuid">,
+  ) =>
+    `/${encodeURIComponent(section ?? "null")}/articles/${encodeURIComponent(articleId ?? "null")}/comments/${encodeURIComponent(id ?? "null")}`;
+}

test/features/openapi_v2/src/api/functional/articles/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @packageDocumentation
+ * @module api.functional.articles
+ * @nestia Generated by Nestia - https://github.com/samchon/nestia
+ */
+//================================================================
+export * as comments from "./comments";