How to work with scheme referencing local files?

[showmeyourhits]

Hi, everyone 👋

Our team has a habit of extracting common definitions for Swagger in separate file. For example, service can have a private and a public API and they different endpoints, but similar structure.

For example, repo has such structure:

/docs
|--swagger-private.yaml
|--swagger-public.yaml
|--common.yaml

And in swagger defs there will be something like that:

...
paths:
  /example:
    get:
      summary: Example endpoint
      operationId: ExampleEndpoint
      parameters:
        - $ref: 'common.yaml#/parameters/pageParam'
        - $ref: 'common.yaml#/parameters/perPageParam'
      responses:
        200:
          description: Successful response.
          schema:
            $ref: '#/definitions/ExampleResponse'
        400:
          description: Bad request.
          schema:
            $ref: "common.yaml#/responses/badRequest"
        401:
          description: Unauthorized.
          schema:
            $ref: "common.yaml#/responses/unauthorized"
        403:
          description: Forbidden.
          schema:
            $ref: "common.yaml#/responses/forbidden"
        500:
          description: Internal server error.
          schema:
            $ref: "common.yaml#/definitions/error"

We pass swagger scheme to CLI by URL or absolute fs path:

swagger-typescript-api -p /docs/swagger-private.yaml --union-enums --route-types -o src/modules/api/http -n generatedAPITypes.ts

API client is generated, but there is an issue with it:
a) All the definitions from common.yaml are missing
b) CLI doesn't say anything about missing files or inability to follow $ref.

Scheme documentation defines such references as valid - link.

So question is: how to work with such schemas?

We are using OpenAPI 2.0 aka Swagger.
I encountered this problem on 12.0.4 and 13.0.22 versions.

[showmeyourhits]

After some lurking through the code of this very useful (no sarcasm) tool, I found out that file reference is not supported now - schema-walker.ts only works with http URLs and local refs.

So I rephrase the question: what is your plan to supporting it?

[v-lukoyanov]

I find it unusual that separate spec files are not supported, because this is a very important feature

Please let me know how this can be solved?

Is this planned to be fixed? Maybe there is a working analogue?

Because it is very difficult to keep everything in one spec file