[Bug] OpenAPI Export inlines references ($ref) in Array Items despite correct UI and Preview display

[Tommy]

There is a discrepancy between the Apidog UI/Code Generation preview and the actual exported OpenAPI YAML/JSON file. While a schema referenced within an array (e.g., type: array, items: { $ref: '...' }) displays correctly as a reference in the “Preview” and “Code Generation” tabs, the exported file converts this reference into an inline object.

Expected Behavior

The exported YAML should maintain the reference for array items:

data:
  type: array
  items:
    $ref: '#/components/schemas/User'

Actual Behavior

The exported YAML inlines the entire User object structure inside the items:

data:
  type: array
  items:
    type: object
    properties:
      last_name: { type: string }
      # ... (rest of the object properties)

Environment & Versions

Apidog 2.7.60
OpenAPI 3.0.1 and 3.1

[apidog]

Hello, thank you for your feedback. We were unable to reproduce this issue locally—the exported OpenAPI file correctly preserves the $ref reference in array items.

To help us investigate further, please provide the following information:

1. Screenshot of the export entry point

   • For example: Is it from “Settings → Export” or “APIs → Export”?
   • Are you using “Export” or “Open URL”?

2. JSON Schema of the interface

   • Include the array items configuration with the $ref reference

3. Export the interface in Apidog format

   • This will help us view the complete data structure

Thank you for your cooperation. We will investigate and address this as soon as we receive the information.

[Tommy]

@apidog
Thanks for your quick response.
Here are some screenshots showing the items inside the array are in fact a reference but not perserved after an export. And the apidog export so you can reproduce it.

In the example I just export the folder from the sidebar (I didn’t know there is a difference).

Example Schema referencing another PagenationMetadata and User inside an array:

An API endpoint that returns the UserListResponse schema on 200:

Export via sidebar:

Result does only reference PaginationMetadata and inlines User

bug-report.apidog.json (22.0 KB)

[apidog]

Thank you for your detailed feedback. Our team is currently investigating this issue. We appreciate your patience while we investigate this.

[apidog]

Hello @Tommy, thank you for the detailed information. We’ve identified the issue:

Your response body root node is using Apidog’s internal reference mechanism (x-apidog-refs) via the “Add” button. During OpenAPI export, this causes array items’ $ref references to be inlined as full object structures.

Solution: For the response body root node, directly reference the data model by:

1. Clicking the “object” type selector on the right
2. Changing the type to ““Reference other schemas””

This will export correctly as:

"schema": {
  "$ref": "#/components/schemas/UserListResponse"
}

[Tommy]

Thank you for the quick help!

My workflow is to select ‘Object’, add a child node, and click Reference Schema next to the field name. Should this result in the same outcome, or is it intentional different?

[apidog]

Thank you for your feedback. We’ll consider how to optimize this to ensure consistency between different reference methods.