Resolve File References

[jcbeck37]

Problem:
While OpenAPI supports file references like $ref: './components/paths/myPath.yml this results in "invalid-ref No resolve defined" error, and the properties of the references are not loaded into the preview.

Solution:
A plugin that could read the files of a folder where the OpenAPI file exists, resolving the references would pull the OpenAPI properties into the preview. If necessary, the plugin might offer up a UI to select the default root path.

[nijikokun]

Absolutely, awesome request.

Folder support would be absolutely amazing, and I've sent this over to our designer @jitachi who is currently working on the new sidebar to make sure we aren't painting ourselves into a corner, and to get insights from community input.

[kroleg]

This functionality (resolving file references) is a must have. I think it should not be a plugin, it should be core feature (It's a core feature of OpenAPI)

[KamilKot95]

+1

[nijikokun]

@kroleg absolutely, core functionality to support multi-file is something we are actively thinking about.

[jmccarrell-lmi]

Can the title be changed to reflect that it will be a core feature and not a plugin?

It may help alleviate some concerns for folks who consider this an absolute must have.

[salewski]

Just leaving a longer-form representation of the validation error message since Google did not turn up this issue when I looked[0]:

    invalid-ref No resolver defined for scheme 'file' in ref components/schemas/your-file-name.yaml

[0] I found my way here via Hacker News comments, into which I happened to wander.

[st-schneider]

Is there an update on this?

[Namphibian]

Yeah this is kind of a deal breaker for me. Not being able to declare some common models in a separate file and having to break the DRY principle is like getting a $7 note in change.... it does not sit well with me.

[xaocon]

Anyone want to try to tag team this? I don't have much backend JS/TS experience but the lib the package uses says it works with $ref so it seems like it shouldn't be too hard to do.

[xaocon]

I started digging into this a little and I imagine one of the reasons this hasn't been done yet is because it would need to change a number of files. I think this could be fixed with only changes to the insomnia-importers package, which is quite handy on it's own.

Currently, however, it takes a filename, then reads out the contents and passes it on to all the different importers looking for one that will handle it correctly. All the different importer libraries accept file contents strings rather than a file name. This means that swagger-parser package doesn't get enough information to build a full object. Luckily, swagger parsers API isn't too large and hasn't changed a whole lot from 6.x.x (current in insomnia) to 10.x.x (upstream current) and updating the libraries that parse would be a fairly minimal job. Unfortunately, we'd need to change how all the parser libraries work so they can work with a new input. It may be easiest to simply pass the filename in addition to the file contents so that libraries that expect file contents can continue working with only a minimal change.

These are just some preliminary notes for anyone following along at home. Again, I'd be willing to help with making a PR for this but I'll probably need someone with more node knowledge than me to check my work and maybe help steer me in the correct direction before I try changing everything.

[Namphibian]

@xaocon thanks for the look into it.

One thing we do is top down API development, we generate the code from the contract/interface definition. So there is a concern for me at this point is that most of the code generator do not seem to handle multiple files. If that is the case we would probably need to have all files joined into one for export. Will investigate this a little more over the following days and get back to you.

[xaocon]

@Namphibian I'll defer to you guys just trying to be helpful in getting this out.

[xaocon]

I should be clear that you pass a single path to the library and it opens the additional files as necessary.

[pumpkinlink]

I'm having a similar problem, but with remote https references instead of files.
The structure is correctly rendered in the Design -> Preview pane, the example JSON payload is correctly generated in Debug, which means that appareantly the https ref works. Despite this, everytime I switch to Debug window, the appliaction gives me this annoying popup about errors in specification, then I have to click "Proceed"

Shoud I open a separate issue about this?

My code is somewhat like this:

openapi: 3.0.0
info:
  title: Process Service
  license:
    name: Proprietary
paths:
  /process:
    post:
      summary: Create new processing request
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessRequest"
components:
  schemas:
    Polygon:
      $ref: https://geojson.org/schema/Polygon.json # <-- **This is line 458**
    ProcessRequest:
      type: object
      properties:
        "type":
          type: string
          enum:
            - "Feature"
        "properties":
          $ref: "#/components/schemas/NewProcess"
        "geometry":
          $ref: "#/components/schemas/Polygon"
    NewProcess:
      type: object
      properties:
      # [redacted]

[topher515]

Since the solution, for now, is to merge the OpenAPI files into a single file. I found this helpful to perform the merge: https://stackoverflow.com/a/54586138/273637

npm install speccy -g
speccy resolve path/to/spec.yaml -o spec-output.yaml

Hopefully that helps someone.

[andrei-dascalu]

Although this is a core part of OpenAPI spec, it seems there's still no consensus or movement to support it after 3 years. Without this, seems that support for OpenAPI can be considered incomplete at best.