feat(flags): add ability to substitute path parameter names with their respective types (#891)

Issue #889

Co-authored-by: Drew Powers <1369770+drwpow@users.noreply.github.com>

Author: Powell-v2

README.md

@@ -161,6 +161,7 @@ npx openapi-typescript schema.yaml
 | `--export-type`                |       | `false`  | (optional) Export `type` instead of `interface`                                                                                         |
 | `--support-array-length`       |       | `false`  | (optional) Generate tuples using array minItems / maxItems                                                                              |
 | `--make-paths-enum`            | `-pe` | `false`  | (optional) Generate an enum of endpoint paths                                                                                           |
+| `--path-params-as-types`       |       | `false`  | (optional) Substitute path parameter names with their respective types                                                                  |
 | `--raw-schema`                 |       | `false`  | Generate TS types from partial schema (e.g. having `components.schema` at the top level)                                                |
 | `--version`                    |       |          | Force OpenAPI version with `--version 3` or `--version 2` (required for `--raw-schema` when version is unknown)                         |
 

bin/cli.js

@@ -29,6 +29,7 @@ Options
   --paths-enum, -pe            (optional) Generate an enum containing all API paths.
   --export-type                (optional) Export type instead of interface
   --support-array-length       (optional) Generate tuples using array minItems / maxItems
+  --path-params-as-types       (optional) Substitute path parameter names with their respective types
   --version                    (optional) Force schema parsing version
 `;
 
@@ -45,7 +46,7 @@ function errorAndExit(errorMessage) {
 const [, , input, ...args] = process.argv;
 const flags = parser(args, {
   array: ["header"],
-  boolean: ["defaultNonNullable", "immutableTypes", "rawSchema", "makePathsEnum", "exportType", "supportArrayLength"],
+  boolean: ["defaultNonNullable", "immutableTypes", "rawSchema", "exportType", "supportArrayLength", "makePathsEnum", "pathParamsAsTypes"],
   number: ["version"],
   string: ["auth", "header", "headersObject", "httpMethod", "prettierConfig"],
   alias: {
@@ -97,6 +98,7 @@ async function generateSchema(pathToSpec) {
     httpMethod: flags.httpMethod,
     exportType: flags.exportType,
     supportArrayLength: flags.supportArrayLength,
+    pathParamsAsTypes: flags.pathParamsAsTypes,
   });
 
   // output

src/index.ts

@@ -45,6 +45,7 @@ async function openapiTS(
     makePathsEnum: options.makePathsEnum || false,
     version: options.version || 3,
     supportArrayLength: options.supportArrayLength,
+    pathParamsAsTypes: options.pathParamsAsTypes,
   };
 
   // note: we may be loading many large schemas into memory at once; take care to reuse references without cloning

src/transform/paths.ts

@@ -1,5 +1,5 @@
 import type { GlobalContext, OperationObject, ParameterObject, PathItemObject } from "../types.js";
-import { comment, tsReadonly } from "../utils.js";
+import { comment, tsReadonly, nodeType } from "../utils.js";
 import { transformOperationObj } from "./operation.js";
 import { transformParametersArray } from "./parameters.js";
 
@@ -8,6 +8,24 @@ interface TransformPathsObjOption extends GlobalContext {
   operations: Record<string, { operation: OperationObject; pathItem: PathItemObject }>;
 }
 
+const httpMethods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"] as const;
+
+function replacePathParamsWithTypes(url: string, params: NonNullable<PathItemObject["parameters"]>) {
+  let result = url;
+
+  params.forEach((param) => {
+    if ("in" in param && param.in === "path") {
+      if (param.schema && "type" in param.schema) {
+        result = result.replace(`{${param.name}}`, `\${${nodeType(param.schema)}}`);
+      } else if (param.type) {
+        result = result.replace(`{${param.name}}`, `\${${nodeType({ type: param.type })}}`);
+      }
+    }
+  });
+
+  return result;
+}
+
 /** Note: this needs to mutate objects passed in */
 export function transformPathsObj(paths: Record<string, PathItemObject>, options: TransformPathsObjOption): string {
   const { globalParameters, operations, ...ctx } = options;
@@ -23,10 +41,30 @@ export function transformPathsObj(paths: Record<string, PathItemObject>, options
       continue;
     }
 
-    output += ` ${readonly}"${url}": {\n`; // open PathItem
+    let key = `"${url}"`;
+
+    if (url.includes("{") && url.includes("}") && ctx.pathParamsAsTypes) {
+      let params;
+
+      if (pathItem.parameters) {
+        params = pathItem.parameters;
+      } else {
+        const firstMethodParams = Object.values(pathItem)
+          .map((props) => typeof props === "object" && props.parameters)
+          .filter(Boolean)[0];
+
+        if (firstMethodParams) {
+          params = firstMethodParams;
+        }
+      }
+
+      key = `[key: \`${replacePathParamsWithTypes(url, params)}\`]`;
+    }
+
+    output += ` ${readonly}${key}: {\n`; // open PathItem
 
     // methods
-    for (const method of ["get", "put", "post", "delete", "options", "head", "patch", "trace"]) {
+    for (const method of httpMethods) {
       const operation = (pathItem as any)[method];
       if (!operation) continue; // only allow valid methods
       if (operation.description) output += comment(operation.description); // add comment

src/types.ts

@@ -161,6 +161,10 @@ export interface SwaggerToTSOptions {
    * (optional) Generate tuples using array minItems / maxItems
    */
   supportArrayLength?: boolean;
+  /**
+   * (optional) Substitute path parameter names with their respective types.
+   */
+  pathParamsAsTypes?: boolean;
 }
 
 /** Context passed to all submodules */
@@ -177,4 +181,5 @@ export interface GlobalContext {
   makePathsEnum: boolean;
   version: number;
   supportArrayLength?: boolean;
+  pathParamsAsTypes?: boolean;
 }

test/core/paths.test.js

@@ -487,4 +487,42 @@ describe("transformPathsObj", () => {
   };`)
     );
   });
+
+  it("transforms path params into explicit types (#889)", () => {
+    expect(
+      format(
+        transform(
+          {
+            "/{XXX}/nested/{YYY}": {
+              get: { responses: {} },
+              parameters: [
+                { name: "XXX", in: "path", required: true, schema: { type: "string" } },
+                { name: "YYY", in: "path", required: true, schema: { type: "integer" } },
+              ],
+            },
+          },
+          { ...defaults, pathParamsAsTypes: true }
+        )
+      )
+    ).to.equal(
+      format(`
+        [key: \`/\${string}/nested/\${number}\`]: {
+          get: {
+            parameters: {
+              path: {
+                XXX: string;
+                YYY: number;
+              };
+            };
+            responses: {};
+          };
+          parameters: {
+            path: {
+              XXX: string;
+              YYY: number;
+            };
+          };
+        };`)
+    );
+  });
 });