improve dynamic route detection; add test cases; add 202 resp

Author: DylanBulmer

.swcrc

@@ -1,5 +1,5 @@
 {
-  "$schema": "http://json.schemastore.org/swcrc",
+  "$schema": "https://json.schemastore.org/swcrc.json",
   "jsc": {
     "parser": {
       "syntax": "typescript",

jest.config.json

@@ -1,7 +1,7 @@
 {
   "transform": {
-    "^.+\\.(t|j)sx?$": ["@swc/jest"]
+    "^.+\\.(t|j)sx?$": "@swc/jest"
   },
-  "testRegex": "/__tests__/.*\\.(test|spec)\\.(jsx?|tsx?)$",
+  "testRegex": "/src/__tests__/.*\\.(test|spec)\\.(jsx?|tsx?)$",
   "moduleFileExtensions": ["ts", "tsx", "js", "jsx", "json", "node"]
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dylanbulmer/openapi",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "main": "index.js",
   "author": "Dylan Bulmer <dylan@bulmersolutions.com>",
   "license": "MIT",

src/__tests__/DynamicRoutes/DynamicRoutes.test.ts

@@ -6,7 +6,6 @@ import apiDoc from "../api-doc";
 
 test("Dynamic routes", () => {
   const app = express();
-
   return initialize({
     app,
     api: {
@@ -19,14 +18,15 @@ test("Dynamic routes", () => {
       // url: "/docs/elements"
     },
   }).then(doc => {
-    // check if dynamic route exists
-    expect(Object.keys(doc.paths as OpenAPIV3_1.PathsObject)).toContain(
-      "/{test}",
+    const paths = doc.paths as OpenAPIV3_1.PathsObject;
+    const pathKeys = Object.keys(paths);
+    // check if dynamic route file exists
+    expect(pathKeys).toContain("/{test}");
+    expect(paths["/{test}"]?.get?.description).toBe("Testing dynamic routes");
+    // check if dynamic route folder exists
+    expect(pathKeys).toContain("/{test2}");
+    expect(paths["/{test2}"]?.get?.description).toBe(
+      "Testing dynamic folder as route",
     );
-
-    // check if dynamic route's GET description is set
-    expect(
-      (doc.paths as OpenAPIV3_1.PathsObject)["/{test}"]?.get?.description,
-    ).toBe("Testing dynamic routes");
   });
 });

src/__tests__/DynamicRoutes/routes/[test2]/index.ts

@@ -0,0 +1,35 @@
+import { Operation } from "../../../../types/Route";
+
+export const GET: Operation =
+  /* business middleware not expressible by OpenAPI documentation goes here */
+  (req, res) => {
+    res.status(200).json({ detail: { message: "OK" } });
+  };
+
+// 3.0 specification
+GET.apiDoc = {
+  description: "Testing dynamic folder as route",
+  tags: ["TEST"],
+  responses: {
+    "200": {
+      $ref: "#/components/responses/200",
+      content: {
+        "application/json": {
+          schema: {
+            properties: {
+              detail: {
+                type: "object",
+                properties: {
+                  message: {
+                    type: "string",
+                    examples: ["OK"],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};

src/classes/responses/202.ts

@@ -0,0 +1,28 @@
+import { OpenAPIV3_1 } from "openapi-types";
+
+const R200: OpenAPIV3_1.ResponseObject = {
+  description: `The HyperText Transfer Protocol (HTTP) \`202 Accepted\` response status code indicates that the request has been accepted for processing, but the processing has not been completed; in fact, processing may not have started yet. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
+
+  202 is non-committal, meaning that there is no way for the HTTP to later send an asynchronous response indicating the outcome of processing the request. It is intended for cases where another process or server handles the request, or for batch processing.
+([mdn docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202))`,
+  content: {
+    "application/json": {
+      schema: {
+        allOf: [{ $ref: "#/components/schemas/GenericSchema" }],
+        properties: {
+          detail: {
+            type: "object",
+            properties: {
+              message: {
+                type: "string",
+                examples: ["accepted"],
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+export default R200;

src/index.ts

@@ -46,6 +46,7 @@ export const initialize = function initialize({ app, api, ui }: IOptions) {
                 : defaultDoc;
             }
 
+            // apply the route to express app.
             switch (key) {
               case "GET":
                 app.get(r.url.express, operation);
@@ -124,33 +125,32 @@ const getFiles = async function* getFiles(
     } else {
       // else get file name and return details
       const routePath = dirent.name.replace(/\.(t|j)s/g, "");
-      let routeName = routePath;
-      let expressUrl: string;
-      let openapiUrl: string;
+      let currentPath;
 
-      // if route is dynamic, extract route name and adjust for express and openapi formating
-      const nameRegex = /\[(?<name>.+)\]/i;
-      if (nameRegex.test(routeName)) {
-        routeName = routeName.match(nameRegex)?.groups?.name as string;
-        expressUrl = `${basePath}:${routeName}`;
-        openapiUrl = `${basePath}{${routeName}}`;
-      } else if (routeName === "index") {
+      // if route name is index, update url structure
+      if (routePath === "index") {
+        // if the base path is the root, change current path to root.
         if (basePath === "/") {
-          expressUrl = `${basePath}`;
-          openapiUrl = `${basePath}`;
-        } else {
+          currentPath = basePath;
+        }
+        // else update current path with the base path without the trailing slash.
+        else {
           const base = basePath.substring(0, basePath.length - 1);
-          expressUrl = `${base}`;
-          openapiUrl = `${base}`;
+          currentPath = base;
         }
-      } else {
-        expressUrl = `${basePath}${routeName}`;
-        openapiUrl = `${basePath}${routeName}`;
+      }
+      // else set the current path to base path plus the route path
+      else {
+        currentPath = `${basePath}${routePath}`;
       }
 
+      // yeild result, replacing all dynamic routes to their appropriate form.
       yield {
-        url: { express: expressUrl, openapi: openapiUrl },
-        name: routeName,
+        url: {
+          express: currentPath.replace(/\[(?<name>.+)\]/i, ":$1"),
+          openapi: currentPath.replace(/\[(?<name>.+)\]/i, "{$1}"),
+        },
+        name: routePath,
         path: `${basePath}${routePath}`,
       };
     }