Merge pull request #2558 from kubb-labs/copilot/sub-pr-2555

Author: stijnvanhulle

packages/oas/mocks/category.yaml

@@ -0,0 +1,14 @@
+openapi: 3.0.3
+info:
+  title: Category
+  version: 1.0.0
+components:
+  schemas:
+    Category:
+      type: object
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string

packages/oas/mocks/petStoreExternalFileRef.yaml

@@ -0,0 +1,20 @@
+openapi: 3.0.3
+info:
+  title: PetStore with external file ref
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        category:
+          $ref: './category.yaml#/components/schemas/Category'

packages/oas/src/utils.spec.ts

@@ -82,6 +82,39 @@ components:
     )
     expect(oas.api?.info.title).toBe('Swagger PetStore')
   })
+
+  test('parse a spec with an external file $ref preserves the $ref pointer', async () => {
+    const specPath = path.resolve(__dirname, '../mocks/petStoreExternalFileRef.yaml')
+    const oas = await parse(specPath)
+
+    expect(oas).toBeDefined()
+    expect(oas.api?.info.title).toBe('PetStore with external file ref')
+    // The $ref pointer must be preserved (not inlined) so SchemaGenerator can emit a named type reference
+    const petSchema = (oas.api as any).components?.schemas?.Pet
+    expect(petSchema).toBeDefined()
+    expect(petSchema.type).toBe('object')
+    expect(petSchema.required).toEqual(['id', 'name'])
+    expect(petSchema.properties.id).toEqual({ type: 'integer', format: 'int64' })
+    expect(petSchema.properties.name).toEqual({ type: 'string' })
+    expect(petSchema.properties.category.$ref).toBe('./category.yaml#/components/schemas/Category')
+  })
+
+  test('parse a spec with an external URL $ref preserves the $ref pointer', async () => {
+    const specPath = path.resolve(__dirname, '../../plugin-ts/mocks/petStore.yaml')
+    const oas = await parse(specPath)
+
+    expect(oas).toBeDefined()
+    expect(oas.api?.info.title).toBe('Swagger PetStore')
+    // The external HTTP $ref must be preserved (not inlined) so SchemaGenerator can emit a named type reference
+    const petSchema = (oas.api as any).components?.schemas?.Pet
+    expect(petSchema).toBeDefined()
+    expect(petSchema.type).toBe('object')
+    expect(petSchema.required).toEqual(['id', 'name'])
+    expect(petSchema.properties.id).toEqual({ type: 'integer', format: 'int64' })
+    expect(petSchema.properties.name).toEqual({ type: 'string' })
+    expect(petSchema.properties.tag).toEqual({ type: 'string' })
+    expect(petSchema.properties.category.$ref).toBe('https://petstore3.swagger.io/api/v3/openapi.json#/components/schemas/Category')
+  })
 })
 
 describe('parseFromConfig', () => {

packages/oas/src/utils.ts

@@ -162,14 +162,8 @@ export function getDefaultValue(schema?: SchemaObject): string | undefined {
 
 export async function parse(
   pathOrApi: string | Document,
-  { oasClass = Oas, canBundle = true, enablePaths = true }: { oasClass?: typeof Oas; canBundle?: boolean; enablePaths?: boolean } = {},
+  { oasClass = Oas, enablePaths = true }: { oasClass?: typeof Oas; canBundle?: boolean; enablePaths?: boolean } = {},
 ): Promise<Oas> {
-  if (typeof pathOrApi === 'string' && canBundle) {
-    // resolve external refs using oas-normalize (already a dependency)
-    const bundled = await new OASNormalize(pathOrApi, { enablePaths, colorizeErrors: true }).bundle()
-    return parse(bundled as Document, { oasClass, canBundle: false, enablePaths })
-  }
-
   const oasNormalize = new OASNormalize(pathOrApi, {
     enablePaths,
     colorizeErrors: true,
@@ -188,7 +182,7 @@ export async function parse(
 }
 
 export async function merge(pathOrApi: Array<string | Document>, { oasClass = Oas }: { oasClass?: typeof Oas } = {}): Promise<Oas> {
-  const instances = await Promise.all(pathOrApi.map((p) => parse(p, { oasClass, enablePaths: false, canBundle: false })))
+  const instances = await Promise.all(pathOrApi.map((p) => parse(p, { oasClass, enablePaths: false })))
 
   if (instances.length === 0) {
     throw new Error('No OAS instances provided for merging.')

packages/plugin-oas/src/plugin.ts

@@ -130,7 +130,15 @@ export const pluginOas = definePlugin<PluginOas>((options) => {
         return
       }
 
-      await oas.dereference()
+      await oas.dereference().catch((err: unknown) => {
+        // Some specs have invalid internal $ref pointers (e.g. `#/definitions/...` in OpenAPI 3.x docs)
+        // that cause dereference to fail. Log the issue and continue — the SchemaGenerator resolves
+        // refs on-the-fly via dereferenceWithRef(), so schema generation still works.
+        this.events.emit('debug', {
+          date: new Date(),
+          logs: [`Unable to fully dereference schema: ${(err as Error).message}`],
+        })
+      })
 
       const schemaGenerator = new SchemaGenerator(
         {

packages/plugin-redoc/src/plugin.ts

@@ -22,7 +22,11 @@ export const pluginRedoc = definePlugin<PluginRedoc>((options) => {
     pre: [pluginOasName],
     async install() {
       const oas = await this.getOas()
-      await oas.dereference()
+      await oas.dereference().catch((err: unknown) => {
+        // Some specs have invalid internal $ref pointers (e.g. `#/definitions/...` in OpenAPI 3.x docs)
+        // that cause dereference to fail. Continue with the un-dereferenced spec.
+        void err
+      })
 
       const root = path.resolve(this.config.root, this.config.output.path)
       const pageHTML = await getPageHTML(oas.api)