broken local $ref

[kresli]

Using $ref somehow breaks generated types. I'm new with openapi and with the library so my apologies if fault is mine but following setup will produce wrong types 🤔
https://gitpod.io#snapshot/50d6481d-7417-4c11-97dd-b84e84f71af5

run yarn generate
and check schema.ts

I spent hours on the and schema looks ok. Whats strange to me is following output

export interface external {
  "components/current.yml": {
    paths: {};
    components: {};
    operations: {};
  };
  "paths/current.yml": {
    paths: {};
    components: {};
    operations: {};
  };
}

where the components interface accessing non existing path

export interface components {
  readonly schemas: {
    readonly full_user: external["components/current.yml"]["full_user"];
  };
}

[drwpow]

How are your types broken? I’d need to see the following:

1. A complete schema, or at least a valid snippet of your schema that’s breaking
2. The output that openapi-typescript is generating
3. Your desired output (i.e. how Remove spaces in enum names #2 isn’t as expected).

Whats strange to me is following output

That all seems correct, actually. But in order for that local $ref to work I believe current.yml will have to be in the same folder as your root schema. Is that correct?

[jkryl]

I have a problem with local ref too. Though I'm using the openapi generator the first time, so maybe I'm doing something wrong. The case is as follows:

Simplified openapi scheme snippet:

"paths": {
    "/public/Time": {
      "get": {
        "summary": "Get Server Time",
        "description": "Get the server's time.",
        "operationId": "getServerTime",
        "responses": {
          "200": {
            "description": "Success response",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Success response",
                  "type": "object",
                  "properties": {
                    "result": {
                      "title": "ServerTime",
                      "type": "object",
                      "properties": {
                        "unixtime": {
                          "description": "Unix timestamp",
                          "type": "integer"
                        },
                        "rfc1123": {
                          "description": "RFC 1123 time format",
                          "type": "string"
                        }
                      }
                    },
                    "error": {
                      "$ref": "#/paths/~1private~1Stake/post/responses/200/content/application~1json/schema/properties/error"
                    }
                  }
                },

Notice the reference in error. It correctly points to a type defined in the same file here (again simplified):

    "/private/Stake": {
      "post": {
        "summary": "Stake Asset",
        "description": "Stake an asset",
        "operationId": "stake",
        "responses": {
          "200": {
            "description": "Staking successful.",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "result": {
                      "type": "object",
                      "properties": {
                        "refid": {
                          "type": "string",
                          "description": "Reference ID",
                          "example": "BOG5AE5-KSCNR4-VPNPEV"
                        }
                      }
                    },
                    "error": {
                      "type": "array",
                      "items": {
                        "description": "API error",
                        "type": "string",
                        "example": "EGeneral:Invalid arguments"
                      }
                    }
                  }
                },

Now if we look at the generated code, it tries to use the same reference path as in the scheme:

  /** Get the server's time. */
  getServerTime: {
    responses: {
      /** Success response */
      200: {
        content: {
          "application/json": {
            result?: {
              /** Unix timestamp */
              unixtime?: number;
              /** RFC 1123 time format */
              rfc1123?: string;
            };
            error?: paths["/private/Stake"]["post"]["responses"]["200"]["content"]["application/json"]["schema"]["error"];
          };
        };
      };
    };
  };

But that does not exist in the generated TS file. It only existed in the scheme:

export interface paths {
  ...
  "/private/Stake": {
    /** Stake an asset from your spot wallet. This operation requires an API key with `Withdraw funds` permission. */
    post: operations["stake"];
  };
  ...
}
export interface operations {
  ...
  stake: {
    responses: {
      /** Staking successful. */
      200: {
        content: {
          "application/json": {
            result?: {
              /** Reference ID */
              refid?: string;
            };
            error?: string[];
          };
        };
      };
    };

Looks like a bug to me.

[jkryl]

Reading official swagger documentation that suggests that common type definitions should be placed under "components". However it is not clear to me if it's a recommendation or a mandatory rule:

Often, multiple API operations have some common parameters or return the same response structure. To avoid code duplication, you can place the common definitions in the global components section and reference them using $ref. In the example below, duplicate definitions of a User object are replaced with a single component and references to that component.