Not generating types for remote $ref in path parameters

[asda-arantxa-gomez]

Description

When attempting to generate code from an OpenAPI document that included remote $ref as path parameters (storeNumber), these path parameters are ignored when types are generated.

openapi-generator version

5.4.1

node version

14.17.6

OpenAPI declaration file content

openapi: 3.1.0
x-stoplight:
  id: f8f10zekkrr1n
info:
  title: Test
  version: '1.0'
  summary: API to manage customers database
  description: This api will be used to manage data in the customers database
  contact:
    name: Company Name
servers:
  - url: 'http://localhost:3000'
paths:
  '/customers/{storeNumber}/{customerId}':
    parameters:
      - schema:
          type: string
        name: customerId
        in: path
        required: true
        description: customer unique identifier
      - $ref: ./common.yaml#/components/parameters/storeNumber
    get:
      summary: Get User Info by User ID
      tags:
        - Customers
      responses:
        '200':
          description: User Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Get User Alice Smith:
                  value:
                    id: 142
                    firstName: Alice
                    lastName: Smith
                    email: [email protected]
                    dateOfBirth: '1997-10-31'
                    emailVerified: true
                    signUpDate: '2019-08-24'
      operationId: get-users-userId
      description: Retrieve the information of the user with the matching user ID.
    patch:
      summary: Update User Information
      operationId: patch-users-userId
      responses:
        '200':
          description: User Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                Updated User Rebecca Baker:
                  value:
                    id: 13
                    firstName: Rebecca
                    lastName: Baker
                    email: [email protected]
                    dateOfBirth: '1985-10-02'
                    emailVerified: false
                    createDate: '2019-08-24'
      description: Update the information of an existing user.
      tags:
        - Customers
components:
  schemas:
    User:
      title: User
      type: object
      description: ''
      examples:
        - id: 142
          firstName: Alice
          lastName: Smith
          email: [email protected]
          dateOfBirth: '1997-10-31'
          emailVerified: true
          signUpDate: '2019-08-24'
      properties:
        id:
          type: integer
          description: Unique identifier for the given user.
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
          format: email
        dateOfBirth:
          type: string
          format: date
          example: '1997-10-31'
        emailVerified:
          type: boolean
          description: Set to true if the user's email has been verified.
        createDate:
          type: string
          format: date
          description: The date that the user was created.
      required:
        - id
        - firstName
        - lastName
        - email
        - emailVerified
tags:
  - name: Customers

Code generated

/**
 * This file was auto-generated by openapi-typescript.
 * Do not make direct changes to the file.
 */
export interface paths {
  '/customers/{storeNumber}/{customerId}': {
    /** Retrieve the information of the user with the matching user ID. */
    get: operations['get-users-userId'];
    /** Update the information of an existing user. */
    patch: operations['patch-users-userId'];
    parameters: {
      path: {
        /** customer unique identifier */
        customerId: string;
      };
    };
  };
}
export interface components {
  schemas: {
    /** User */
    User: {
      /** @description Unique identifier for the given user. */
      id: number;
      firstName: string;
      lastName: string;
      /** Format: email */
      email: string;
      /**
       * Format: date
       * @example 1997-10-31
       */
      dateOfBirth?: string;
      /** @description Set to true if the user's email has been verified. */
      emailVerified: boolean;
      /**
       * Format: date
       * @description The date that the user was created.
       */
      createDate?: string;
    };
  };
}
export interface operations {
  /** Retrieve the information of the user with the matching user ID. */
  'get-users-userId': {
    parameters: {
      path: {
        /** customer unique identifier */
        customerId: string;
      };
    };
    responses: {
      /** User Found */
      200: {
        content: {
          'application/json': components['schemas']['User'];
        };
      };
    };
  };
  /** Update the information of an existing user. */
  'patch-users-userId': {
    parameters: {
      path: {
        /** customer unique identifier */
        customerId: string;
      };
    };
    responses: {
      /** User Updated */
      200: {
        content: {
          'application/json': components['schemas']['User'];
        };
      };
    };
    /** Patch user properties to update. */
  };
}
export interface external {
  'common.yaml': {
    paths: {};
    components: {
      schemas: {};
      parameters: {
        /** @description The store number, in four digit format (leading zero padded) */
        storeNumber: string;
      };
    };
    operations: {};
  };
}

Issue:

I cannot reference the type paths['/customers/{storeNumber}/{customerId}]['parameters']['path']['storeNumber'] because it has not been generated.

Expected:

export interface paths {
  '/customers/{storeNumber}/{customerId}': {
    /** Retrieve the information of the user with the matching user ID. */
    get: operations['get-users-userId'];
    /** Update the information of an existing user. */
    patch: operations['patch-users-userId'];
    parameters: {
      path: {
        /** customer unique identifier */
        customerId: string;
       /** The store number, in four digit format (leading zero padded) */
        storeNumber: string;
      };
    };
  };
}

Actual:

export interface paths {
  '/customers/{storeNumber}/{customerId}': {
    /** Retrieve the information of the user with the matching user ID. */
    get: operations['get-users-userId'];
    /** Update the information of an existing user. */
    patch: operations['patch-users-userId'];
    parameters: {
      path: {
        /** customer unique identifier */
        customerId: string;
      };
    };
  };
}

Similar issue:

#918

[weiyang-xendit]

what does the remote file common.yaml look like?

[asda-arantxa-gomez]

This is the common.yaml file, this file is generated from a reference: ../../../node_modules/@company/func-shared/common.yaml

openapi: 3.1.0
info:
  version: 1.0.0
  title: Customers Common API Elements
  description: Shared OpenAPI Elements used across multiple Customers Domain Services
  contact:
    name: Company Ltd
    url: 'https://www.company.com'
tags:
  - name: Customers
components:
  parameters:
    storeNumber:
      name: storeNumber
      in: path
      required: true
      schema:
        type: string
        pattern: '^\d{4}$'
        example: '0123'
      description: 'The store number, in four digit format (leading zero padded)'
  schemas: {}

[weiyang-xendit]

@asda-arantxa-gomez I found a workaround, not sure if this is will be helpful.

In the main openapi declaration file:

paths:
  /customers/{storeNumber}/{customerId}:
    parameters:
      - schema:
          type: string
        name: customerId
        in: path
        required: true
        description: customer unique identifier
      - $ref: '#/components/parameters/storeNumber' # reference a parameter within the file

components:
  parameters:
    storeNumber:
      in: path # must indicate that parameter is in the path
      $ref: './common.yaml#/components/parameters/storeNumber' # local parameter is a proxy for external parameter

This workaround will generate the following typescript code that contains the storeNumber reference that was initially missing:

export interface paths {
  "/customers/{storeNumber}/{customerId}": {
    /** Retrieve the information of the user with the matching user ID. */
    get: operations["get-users-userId"];
    /** Update the information of an existing user. */
    patch: operations["patch-users-userId"];
    parameters: {
      path: {
        /** customer unique identifier */
        customerId: string;
        storeNumber?: components["parameters"]["storeNumber"];
      };
    };
  };
}

export interface components {
  parameters: {
    storeNumber: external["common.yaml"]["components"]["parameters"]["storeNumber"];
  };
}

export interface external {
  "common.yaml": {
    paths: {};
    components: {
      schemas: {};
      parameters: {
        /** @description The store number, in four digit format (leading zero padded) */
        storeNumber: string;
      };
    };
    operations: {};
  };
}

[asda-arantxa-gomez]

@weiyang-xendit Thank you for your reply.
I will try to use this workaround for now.

[drwpow]

This should be fixed in 6.5.1! But let me know if there are any remaining issues