Support external $ref references in OpenAPI documents

[kyz9rus23]

Feature Request: Support External OpenAPI $ref References

Summary

Please add native support for external $ref references in OpenAPI documents used
by Mintlify's API reference and API playground.

Mintlify currently documents that $ref is supported for internal references
only within a single OpenAPI document, and that external references are not
supported:

https://www.mintlify.com/docs/api-playground/openapi-setup

OpenAPI itself supports splitting API descriptions into multiple connected
documents, including references to external files:

https://spec.openapis.org/oas/v3.1.0.html

Supporting external refs would let teams use Mintlify directly with their
canonical OpenAPI source files instead of requiring a custom pre-bundling step.

Problem

Many spec-first API teams keep OpenAPI definitions modular. A common structure
looks like this:

docs/api-reference/clients-api.yaml
docs/api-reference/internal-api.yaml
docs/api-reference/shared/common_models.yaml
docs/api-reference/shared/common_responses.yaml
docs/api-reference/shared/common_parameters.yaml

Each API spec can then reuse common components:

components:
  schemas:
    SomeModel:
      $ref: "./shared/common_models.yaml#/components/schemas/SomeCommonModel"

This keeps large API definitions maintainable and reduces drift between public,
internal, admin, and partner APIs.

Today, Mintlify cannot consume these source specs directly. Teams must first
bundle them into single-file OpenAPI documents, then point Mintlify to the
generated files. That workaround is functional, but it creates an extra
Mintlify-specific build artifact and another place where docs can drift from the
source of truth.

Why This Is Important

External OpenAPI refs are important because they support maintainable API
documentation at scale.

For small APIs, a single OpenAPI file is manageable. For larger products, one
file quickly becomes difficult to review, validate, and evolve. Shared schemas,
error models, pagination models, headers, request bodies, responses, examples,
and security schemes are often reused across several API surfaces.

Native external ref support would help teams:

• keep one canonical OpenAPI source structure
• avoid duplicating shared models across multiple specs
• reduce inconsistent docs caused by copy-pasted schemas
• use the same specs for documentation, code generation, request validation,
  SDK generation, and CI checks
• simplify local development by removing custom bundling scripts
• make Mintlify easier to adopt in spec-first API workflows

This is especially valuable for teams that maintain multiple OpenAPI files in a
monorepo or documentation repository.

Requested Behavior

Mintlify should resolve external $ref references before rendering API reference
pages and API playground schemas.

Minimum requested scope:

• support local relative file refs inside the documentation repository
• support YAML and JSON referenced files
• support transitive refs, where an imported component references another
  component
• fail with clear, actionable validation errors when a referenced file or JSON
  pointer cannot be resolved

Example refs:

$ref: "./shared/common_models.yaml#/components/schemas/SomeModel"
$ref: "./shared/common_parameters.yaml#/components/parameters/SomeHeaderKey"
$ref: "../common/responses.yaml#/components/responses/SomeResponse"

Ideal full support:

• components.schemas
• components.parameters
• components.responses
• components.headers
• components.requestBodies
• components.examples
• components.securitySchemes
• nested and transitive refs
• circular reference detection
• stable behavior in mint dev, mint validate, preview deployments, and
  production deployments

Remote URL refs could be a separate later enhancement because they introduce
additional caching, network, and security considerations.

Acceptance Criteria

1. A valid OpenAPI 3.0 or 3.1 document with local relative external refs renders
   successfully in Mintlify.
2. API playground request and response schemas render the same way they would if
   the spec had been pre-bundled.
3. mint dev and mint validate report clear errors for missing files, invalid
   JSON pointers, unsupported ref targets, and circular refs.
4. Existing single-file OpenAPI behavior remains unchanged.
5. Multiple OpenAPI specs can reuse the same shared components without requiring
   duplicated definitions.