Issues with references ($ref) resolution

[Ettapp]

Description

Sometimes referenced items (that are correctly resolved by Swagger editor) are output as unknown (see example A) and sometimes they are (see example B)

Name	Version
openapi-typescript	6.7.5
Node.js	20.12.2
OS + version	Ubuntu 23.10

Reproduction

Example A

main.yaml

openapi: 3.0.0
info:
  title: Title
  version: 1.0.0

paths:
  /secondary:
    $ref: 'secondary.yaml#/secondaryPath'

secondary.yaml

components:
  schemas:
    # Issue with the resolution of this schema
    secondaryNestedSchema:
      type: number

# This one works fine
secondaryRootSchema:
  type: string

secondaryPath:
  get:
    tags:
      - Playlist
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                rootSchema:
                  $ref: '#/secondaryRootSchema'
                nestedSchema:
                  $ref: '#/components/schemas/secondaryNestedSchema'

npx openapi-typescript main.yaml will output:

/**
 * This file was auto-generated by openapi-typescript.
 * Do not make direct changes to the file.
 */


export interface paths {
  "/secondary": external["secondary.yaml"]["secondaryPath"];
}

export type webhooks = Record<string, never>;

export type components = Record<string, never>;

export type $defs = Record<string, never>;

export interface external {
  "secondary.yaml": {
    components: unknown;
    secondaryRootSchema: string;
    secondaryPath: {
      get: {
        responses: {
          200: {
            content: {
              "application/json": {
                rootSchema?: external["secondary.yaml"]["secondaryRootSchema"];
                // Error next line: "Property 'schemas' does not exist on type 'unknown'."
                nestedSchema?: external["secondary.yaml"]["components"]["schemas"]["secondaryNestedSchema"];
              };
            };
          };
        };
      };
    };
  };
}

export type operations = Record<string, never>;

Example B

main.yaml

openapi: 3.0.0
info:
  title: Title
  version: 1.0.0

paths:
  /secondary:
    $ref: 'secondary.yaml#/paths/secondaryPath'

secondary.yaml

components:
  schemas:
    secondaryNestedSchema:
      type: number

secondaryRootSchema:
  type: string

paths:
  secondaryPath:
    get:
      tags:
        - Playlist
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  rootSchema:
                    $ref: '#/secondaryRootSchema'
                  nestedSchema:
                    $ref: '#/components/schemas/secondaryNestedSchema'

npx openapi-typescript main.yaml will output:

/**
 * This file was auto-generated by openapi-typescript.
 * Do not make direct changes to the file.
 */


export interface paths {
  "/secondary": external["secondary.yaml"]["paths"]["secondaryPath"];
}

export type webhooks = Record<string, never>;

export type components = Record<string, never>;

export type $defs = Record<string, never>;

export interface external {
  "secondary.yaml": {
    paths: {
      "secondaryPath": {
        get: {
          responses: {
            200: {
              content: {
                "application/json": {
                  // two errors here:
                  // "'rootSchema' is referenced directly or indirectly in its own type annotation."
                  // "'Property 'secondaryRootSchema' does not exist on type..."
                  rootSchema?: external["secondary.yaml"]["secondaryRootSchema"];
                  nestedSchema?: external["secondary.yaml"]["components"]["schemas"]["secondaryNestedSchema"];
                };
              };
            };
          };
        };
      };
    };
    webhooks: Record<string, never>;
    components: {
      schemas: {
        secondaryNestedSchema: number;
      };
      responses: never;
      parameters: never;
      requestBodies: never;
      headers: never;
      pathItems: never;
    };
    $defs: Record<string, never>;
  };
}

export type operations = Record<string, never>;

Checklist

• My OpenAPI schema passes the Redocly validator (npx @redocly/cli@latest lint)¹
• I’m willing to open a PR (see CONTRIBUTING.md)²

Footnotes

1. For the sake of simplicity, I've excluded fields like servers, summary, description, security from the examples, so Redocly warns about it, but I've tested with all the required / recommended fields and the issues still arises. ↩

2. I'll try to find the source of the issue and to submit a PR but if anyone that has better knowledge of the codebase knows how to fix this, do not wait on me ^^ ↩

[fitztrev]

I was getting this too but on v7 it seems to be working

[Ettapp]

It works on v7 indeed, I've somehow missed the existence of the @next version, my bad.