fix(type-safe-api): resolve parameter refs prior to parameter validation

It is legal to use $ref in parameters in an OpenAPI spec, but the validation was assuming these were
not present. Updated the validation to work on a dereferenced clone of the spec. Ensured that the
final parsed spec retains references to ensure the code generator can consolidate models.

Fixes #590

packages/type-safe-api/scripts/type-safe-api/parser/parse-openapi-spec.ts

@@ -4,7 +4,9 @@ import SwaggerParser from "@apidevtools/swagger-parser";
 import { writeFile } from "projen/lib/util";
 import { parse } from "ts-command-line-args";
 import * as path from 'path';
+import * as _ from "lodash";
 import fs from "fs";
+import type { OpenAPIV3 } from "openapi-types";
 
 // Smithy HTTP trait is used to map Smithy operations to their location in the spec
 const SMITHY_HTTP_TRAIT_ID = "smithy.api#http";
@@ -49,6 +51,7 @@ interface Arguments {
   readonly outputPath: string;
 }
 
+
 void (async () => {
   const args = parse<Arguments>({
     specPath: { type: String, alias: "s" },
@@ -101,8 +104,16 @@ void (async () => {
 
   const invalidRequestParameters: InvalidRequestParameter[] = [];
 
+  // Dereference a clone of the spec to test parameters
+  const dereferencedSpec = await SwaggerParser.dereference(JSON.parse(JSON.stringify(spec)), {
+    dereference: {
+      // Circular references are valid, we just ignore them for the purpose of validation
+      circular: "ignore",
+    },
+  });
+
   // Validate the request parameters
-  Object.entries(spec.paths || {}).forEach(([p, pathOp]: [string, any]) => {
+  Object.entries(dereferencedSpec.paths || {}).forEach(([p, pathOp]: [string, any]) => {
     Object.entries(pathOp ?? {}).forEach(([method, operation]: [string, any]) => {
       (operation?.parameters ?? []).forEach((parameter: any) => {
         // Check if the parameter is an allowed type

packages/type-safe-api/test/resources/specs/parameter-refs.yaml

@@ -0,0 +1,39 @@
+openapi: 3.0.3
+info:
+  version: 1.0.0
+  title: Example API
+paths:
+  /hello:
+    get:
+      operationId: sayHello
+      x-handler:
+        language: typescript
+      parameters:
+        - $ref: '#/components/parameters/HelloId'
+      responses:
+        '200':
+          description: Successful response
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/HelloResponse'
+components:
+  parameters:
+    HelloId:
+      in: query
+      name: id
+      schema:
+        $ref: '#/components/schemas/HelloId'
+      required: false
+  schemas:
+    HelloId:
+      type: string
+    HelloResponse:
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/HelloId'
+        message:
+          $ref: '#/components/schemas/HelloResponse'
+      required:
+        - id

packages/type-safe-api/test/scripts/parser/parse-openapi-spec.test.ts

@@ -58,4 +58,20 @@ describe("Parse OpenAPI Spec Script Unit Tests", () => {
       );
     });
   });
+
+  it("Permits parameter references (and circular references)", () => {
+    expect(
+      withTmpDirSnapshot(os.tmpdir(), (tmpDir) => {
+        const specPath = "../../resources/specs/parameter-refs.yaml";
+        const outputPath = path.join(
+          path.relative(path.resolve(__dirname), tmpDir),
+          ".api.json"
+        );
+        const command = `../../../scripts/type-safe-api/parser/parse-openapi-spec --spec-path ${specPath} --output-path ${outputPath}`;
+        exec(command, {
+          cwd: path.resolve(__dirname),
+        });
+      })
+    ).toMatchSnapshot();
+  });
 });