chore(schema): add functionality for handling $ref to /path

This was added to @hey-api/json-schema-ref-parser 1.0.8 but I'm moving it directly to openapi-ts

Author: carson2222

packages/openapi-ts-tests/main/test/3.1.x.test.ts

@@ -44,6 +44,13 @@ describe(`OpenAPI ${version}`, () => {
   };
 
   const scenarios = [
+    {
+      config: createConfig({
+        input: 'external.yaml',
+        output: 'external',
+      }),
+      description: 'handles external references',
+    },
     {
       config: createConfig({
         input: 'pattern-properties.json',
@@ -924,6 +931,7 @@ describe(`OpenAPI ${version}`, () => {
   ];
 
   it.each(scenarios)('$description', async ({ config }) => {
+    // it.each([scenarios[0]])('$description', async ({ config }) => {
     await createClient(config);
 
     const outputPath =

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/external/index.ts

@@ -0,0 +1,2 @@
+// This file is auto-generated by @hey-api/openapi-ts
+export * from './types.gen';

packages/openapi-ts-tests/main/test/__snapshots__/3.1.x/external/types.gen.ts

@@ -0,0 +1,80 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+/**
+ * External schema (A)
+ */
+export type ExternalSchemaA = {
+    id: string;
+    name?: string;
+};
+
+/**
+ * External schema (B)
+ */
+export type ExternalSchemaB = ExternalSchemaA;
+
+/**
+ * External schema (C)
+ */
+export type ExternalSchemaC = ExternalSchemaA;
+
+/**
+ * External schema property (A)
+ */
+export type ExternalSchemaPropertyA = {
+    0?: string;
+};
+
+/**
+ * External schema property (B)
+ */
+export type ExternalSchemaPropertyB = {
+    0?: ;
+};
+
+/**
+ * External schema property from component (A.id)
+ */
+export type ExternalSchemaPropertyFromComponent = {
+    0?: ;
+};
+
+/**
+ * External schema property with duplicate refs (D)
+ */
+export type ExternalSchemaPropertyD = {
+    0?: ;
+    1?: ;
+};
+
+/**
+ * External schema property via external property ref (id)
+ */
+export type ExternalSchemaExternalProp = {
+    0?: ;
+};
+
+/**
+ * Alias to external property via component property ref
+ */
+export type ExternalSchemaExternalPropAlias = {
+    0?: ;
+};
+
+/**
+ * External double nested prop via property ref
+ */
+export type ExternalDoubleNestedProp = {
+    0?: string;
+};
+
+/**
+ * External double nested numeric properties
+ */
+export type ExternalDoubleNestedNumeric = {
+    0?: string;
+};
+
+export type ClientOptions = {
+    baseUrl: `${string}://${string}` | (string & {});
+};

packages/openapi-ts-tests/specs/3.1.x/external-shared.json

@@ -6,5 +6,31 @@
       "name": { "type": "string" }
     },
     "required": ["id"]
+  },
+  "ExternalSharedModelWithUuid": {
+    "type": "string",
+    "format": "uuid"
+  },
+  "ExternalNested": {
+    "type": "object",
+    "properties": {
+      "inner": {
+        "type": "object",
+        "properties": {
+          "deep": { "type": "string" }
+        }
+      }
+    }
+  },
+  "ExternalNestedNumeric": {
+    "type": "object",
+    "properties": {
+      "0": {
+        "type": "object",
+        "properties": {
+          "1": { "type": "string" }
+        }
+      }
+    }
   }
 }

packages/openapi-ts-tests/specs/3.1.x/external.yaml

@@ -0,0 +1,56 @@
+openapi: 3.1.1
+info:
+  title: OpenAPI 3.1.1 external example
+  version: 1
+components:
+  schemas:
+    ExternalSchemaA:
+      description: External schema (A)
+      $ref: './external-shared.json#/ExternalSharedModel'
+    ExternalSchemaB:
+      description: External schema (B)
+      $ref: './external-shared.json#/ExternalSharedModel'
+    ExternalSchemaC:
+      description: External schema (C)
+      $ref: './external-shared.json#/ExternalSharedModel'
+    ExternalSchemaPropertyA:
+      description: External schema property (A)
+      type: object
+      properties:
+        - $ref: './external-shared.json#/ExternalSharedModelWithUuid'
+    ExternalSchemaPropertyB:
+      description: External schema property (B)
+      type: object
+      properties:
+        - $ref: './external-shared.json#/ExternalSharedModelWithUuid'
+    ExternalSchemaPropertyFromComponent:
+      description: External schema property from component (A.id)
+      type: object
+      properties:
+        - $ref: '#/components/schemas/ExternalSchemaA/properties/id'
+    ExternalSchemaPropertyD:
+      description: External schema property with duplicate refs (D)
+      type: object
+      properties:
+        - $ref: './external-shared.json#/ExternalSharedModelWithUuid'
+        - $ref: './external-shared.json#/ExternalSharedModelWithUuid'
+    ExternalSchemaExternalProp:
+      description: External schema property via external property ref (id)
+      type: object
+      properties:
+        - $ref: './external-shared.json#/ExternalSharedModel/properties/id'
+    ExternalSchemaExternalPropAlias:
+      description: Alias to external property via component property ref
+      type: object
+      properties:
+        - $ref: '#/components/schemas/ExternalSchemaExternalProp/properties/0'
+    ExternalDoubleNestedProp:
+      description: External double nested prop via property ref
+      type: object
+      properties:
+        - $ref: './external-shared.json#/ExternalNested/properties/inner/properties/deep'
+    ExternalDoubleNestedNumeric:
+      description: External double nested numeric properties
+      type: object
+      properties:
+        - $ref: './external-shared.json#/ExternalNestedNumeric/properties/0/properties/1'

packages/openapi-ts/src/openApi/2.0.x/parser/schema.ts

@@ -588,6 +588,23 @@ const parseRef = ({
   state: SchemaState;
 }): IR.SchemaObject => {
   const irSchema: IR.SchemaObject = {};
+  // Inline non-component refs (e.g. #/paths/...) to avoid generating orphaned named types
+  const isComponentsRef = schema.$ref.startsWith('#/definitions/');
+  if (!isComponentsRef) {
+    if (!state.circularReferenceTracker.has(schema.$ref)) {
+      const refSchema = context.resolveRef<SchemaObject>(schema.$ref);
+      return schemaToIrSchema({
+        context,
+        schema: refSchema,
+        state: {
+          ...state,
+          $ref: schema.$ref,
+          isProperty: false,
+        },
+      });
+    }
+    // Fallback to preserving the ref if circular
+  }
 
   // refs using unicode characters become encoded, didn't investigate why
   // but the suspicion is this comes from `@hey-api/json-schema-ref-parser`

packages/openapi-ts/src/openApi/3.0.x/parser/schema.ts

@@ -818,6 +818,24 @@ const parseRef = ({
   schema: ReferenceObject;
   state: SchemaState;
 }): IR.SchemaObject => {
+  // Inline non-component refs (e.g. #/paths/...) to avoid generating orphaned named types
+  const isComponentsRef = schema.$ref.startsWith('#/components/');
+  if (!isComponentsRef) {
+    if (!state.circularReferenceTracker.has(schema.$ref)) {
+      const refSchema = context.resolveRef<SchemaObject>(schema.$ref);
+      return schemaToIrSchema({
+        context,
+        schema: refSchema,
+        state: {
+          ...state,
+          $ref: schema.$ref,
+          isProperty: false,
+        },
+      });
+    }
+    // Fallback to preserving the ref if circular
+  }
+
   const irSchema: IR.SchemaObject = {};
 
   // refs using unicode characters become encoded, didn't investigate why

packages/openapi-ts/src/openApi/3.1.x/parser/schema.ts

@@ -810,6 +810,24 @@ const parseRef = ({
   schema: SchemaWithRequired<SchemaObject, '$ref'>;
   state: SchemaState;
 }): IR.SchemaObject => {
+  // Inline non-component refs (e.g. #/paths/...) to avoid generating orphaned named types
+  const isComponentsRef = schema.$ref.startsWith('#/components/');
+  if (!isComponentsRef) {
+    if (!state.circularReferenceTracker.has(schema.$ref)) {
+      const refSchema = context.resolveRef<SchemaObject>(schema.$ref);
+      return schemaToIrSchema({
+        context,
+        schema: refSchema,
+        state: {
+          ...state,
+          $ref: schema.$ref,
+          isProperty: false,
+        },
+      });
+    }
+    // Fallback to preserving the ref if circular
+  }
+
   let irSchema = initIrSchema({ schema });
 
   const irRefSchema: IR.SchemaObject = {};