Feature request: support for external files in $ref

[berzi]

The OpenAPI specification explicitly declares support for splitting specification files into multiple files, referencing the pieces through $ref.

As far as I know, this is not supported by openapi-typescript, and as a result any user of this utility must forgo the ability to split up their API spec file, which for larger applications can result in files spanning multiple thousands of lines.

I think this feature would be a very important addition, not to mention that ideally, the utility should support everything that the OpenAPI specification allows to avoid forcing users out of desirable features.

[drwpow]

This does support remote $refs! There’s even a test for it here.

But perhaps there’s some feature of remote $refs missing? Would love for someone to add more tests to this, and fix any missing parts of the OpenAPI schema this library currently doesn’t support 🙏

[berzi]

Are local $refs also supported?

[drwpow]

In-document $refs are supported, $refs in other files on the local filesystem are supported, and $refs to reachable URLs are supported (this library also has basic auth support if needed). If there is a bug in any of those items, a bug reproduction would be much appreciated 🙏

[berzi]

My colleagues mentioned that much-desired feature didn't work for them. I'll test it out myself soon and report back. :)

[joshunger]

@drwpow can you please give me a tip on what needs to be fixed here?

root.yaml

      responses:
        '200':
          content:
            application/json:
              schema: { $ref: 'coupon_response.yaml#/CouponResponse' }

coupon_response.yaml

CouponResponse:
  type: array
  items: { $ref: 'coupon.yaml#/Coupon' }

Skipping Coupon for now.

Generated:

'application/json': external['coupon_response.yaml']['CouponResponse'];

and

export interface external {
  'coupon_response.yaml': {
    paths: {};
    components: {};
    operations: {};
  };

CouponResponse is missing. Shouldn't something like CouponResponse: external['coupon.yaml']['Coupon'][]; exist here?

I'm ignore the coupon file to try to simplify this example but happy to provide it.

[berzi]

@joshunger Have you tried using paths like ./coupon.yaml and ./coupon_response.yaml?

[berzi]

Anyway I had forgotten to report back as promised. The feature does work even locally, the only issue is that I had to keep the api paths in the central yaml file, so i could only split the components out of it.

[joshunger]

@berzi still empty can you share a snippet you're using? Thanks.

[berzi]

@berzi still empty can you share a snippet you're using? Thanks.

# openapi.yaml

# ...

paths:
  /users/{userId}:
    parameters:
      - $ref: './users.yaml#/components/parameters/UserParameter'
    get:
      description: |
        Information about the currently logged in user.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: './users.yaml#/components/schemas/User'

# users.yaml

# ...

components:
  parameters:
    UserParameter:
      name: userId
      in: path
      schema:
        type: string
      required: true

  schemas:
    User:
      type: object
      required:
          - id
      properties:
        id:
          type: number
        name:
          type: string

[joshunger]

@berzi thanks, putting it under components/schemas fixed the issue for me. Appreciate it!

[ctjhoa]

In my case, paths contains $ref which are pointing to other files on the local filesystem and it doesn't work

Like

    paths:
      /users:
        $ref: '../resources/users.yaml'
      /users/{userId}:
        $ref: '../resources/users-by-id.yaml'

src: https://swagger.io/docs/specification/using-ref/#allowed-places

It fails to generate valid typescript code

SyntaxError: Type expected. (8:13)
   6 |
   7 | export interface paths {
>  8 |   "/users": ../resources/users.yaml;
     |             ^
   9 |   "/users/{userId}": ../resources/users-by-id.yaml;
  10 | }

[berzi]

You're right, that is currently unsupported. Unfortunately I don't have the time to implement this right now though, maybe some other contributor can?

The code is in this function and should simply be instructed to resolve the reference if it is one.

[drwpow]

Update: a recent update did fix some bugs with external $refs. I’m going to close the issue as I believe this has been resolved, but please let me know if anyone is experiencing further issues.