Don't include $ref definitions when path is relative

[alejandrofdiaz]

I've stumble across a problem when splitting my huge openapi spec file in pieces. We decided to take apart some definitions into different files and reference them from our main definition with $ref (as this guide recommends).

Turns out that output definition file does not include that schema, put any instead. I will show you an example:

openapi.yml

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  $ref: "reference.yaml#/account_base"
                  

reference.yaml

account_base:
  type: "object"
  properties:
    id:
      type: "string"
      description: "User's ID"
      example: "26345b2f-3125-11eb-87d8-801234232f4e"
    email:
      type: "string"
      description: "User's Email"
      example: "[email protected]"
      format: "email"

Run cli command: swagger-typescript-api -p ./openapi.yaml -n output.d.ts --no-client --route-types --responses --union-enums

output.d.ts

/* eslint-disable */
/* tslint:disable */
/*
 * ---------------------------------------------------------------
 * ## THIS FILE WAS GENERATED VIA SWAGGER-TYPESCRIPT-API        ##
 * ##                                                           ##
 * ## AUTHOR: acacode                                           ##
 * ## SOURCE: https://github.com/acacode/swagger-typescript-api ##
 * ---------------------------------------------------------------
 */

export namespace users {
  /**
   * @description Optional extended description in CommonMark or HTML.
   * @name UsersList
   * @summary Returns a list of users.
   * @request GET:/users
   * @response `200` `(any)[]` A JSON array of user names
   */
  export namespace UsersList {
    export type RequestParams = {};
    export type RequestQuery = {};
    export type RequestBody = never;
    export type RequestHeaders = {};
    export type ResponseBody = any[]; //<- this should be AccountBase
  }
}

Is this something i can fix by setting a parameter?

[js2me]

Hello @alejandrofdiaz !
Thanks for this issue! Tool doesn't support working with more than one schemas currently, but I'll add this in plans.
This is really helpful feature which should be existed in this project.

[alejandrofdiaz]

Hi @js2me thanks for replying! I'm glad to hear that you're implementing this in the future. In case anybody is interested i found a mild solution in the meantime which uses a tool called speccy to merge openapi definitions (explained here).

This solution does not create individual definitions which swagger-typescript-api can use:

example output.d.ts:

export namespace users {
  /**
   * @description Optional extended description in CommonMark or HTML.
   * @name UsersList
   * @summary Returns a list of users.
   * @request GET:/users
   * @response `200` `({ id?: string, email?: string })[]` A JSON array of user names
   */
  export namespace UsersList {
    export type RequestParams = {};
    export type RequestQuery = {};
    export type RequestBody = never;
    export type RequestHeaders = {};
    export type ResponseBody = { id?: string; email?: string }[]; // <- This should be AccountBase
  }
}

to avoid this you can just not reference those definitions directly from the Response/Request but from a components/schema definition which actually references definition from file apart:

openapi.yaml

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  $ref: "#/components/schemas/account_base" <- Mind this: actually referencing inner component
components:
  schemas:
    account_base:
      $ref: "reference.yaml#/account_base" // <- Mind this: actually referencing external file

This way the output.d.ts is working as usual. I this is useful to create a new feature or to workaround this in the meantime.

[okletstryit]

@js2me hi! any news about this? It would be so helpful having it in this amazing lib