JSON References resolve base path - version 3

[okwei2000]

With version 3 of the editor, it does not resolve relative references. Version 2 seems to have it fixed. https://github.com/swagger-api/swagger-editor/pull/1000

Version 2 of the editor has a preference panel, where the 'Pointer Resolution Base Path' can be set. How this can be done in Version 3?

  Clinic:
    $ref: './Clinic.yaml'

Could not resolve reference because of: Tried to resolve a relative URL, without having a basePath. path: './Clinic.yaml' basePath: 'undefined' Jump to line 59

[webron]

Can you share a full definition?

[okwei2000]

A.yaml (The main file, it's accessible by http://myhost.com/A.yaml)

swagger: '2.0'
info:
  title: Service A
  version: 1.0.0
host: www.myhost.com
schemes:
  - https
basePath: /rest/
produces:
  - application/json
  - application/xml
paths:
  /test:
    get:
      summary: Summary
      consumes:
        - application/json
        - application/xml
      parameters:
        - name: code
          in: query
          description: The code to search for
          required: true
          type: string
      responses:
        '200':
          description: Clinics
          schema:
            $ref: './B.yaml'

B.yaml (in the same directory, http://myhost.com/B.yaml)

properties:
  name:
    type: string

I got error:

Resolver error at paths./test.get.responses.200.schema.$ref Could not resolve reference because of: Tried to resolve a relative URL, without having a basePath. path: './B.yaml' basePath: 'undefined' Jump to line 29

If I replace the $ref: './B.yaml' with $ref: 'http://myhost.com/B.yaml', then everything is OK.

[moon0326]

+1 I'm having the same issue. It would be nice to be able to set 'Pointer Resolution Base Path' in version 3.

[webron]

I don't see the behavior of this being changed soon. The editor works locally and has no knowledge of where the file is hosted.

[gunzip]

@webron that's exactly the reason the 2.x release had the useful option pointerResolutionBasePath

[webron]

I understand, but in terms of priorities, it's not at the top. We'll gladly review PRs though.

[okwei2000]

In the mean time, is there a workaround? can I hard code the pointerResolutionBasePath somewhere in the source code?

[jbinnography]

My workaround has been to use the docker image swaggerapi/swagger.io-editor, which allows you to revert to the 2.x interface and use the old preference settings.

EDIT: Just noticed that the link simply takes you to the hosted version on swagger.io, so if you're trying to do only local work that won't help you.

[joshmaker]

Ouch! I this effectively means I can't use version 3 for big projects where things need to be organized into multiple files for clarity.

[moon0326]

@joshmaker My current workaround..

https://github.com/moon0326/swagger-ui-watcher works fine with local relative path without base path. It now supports OpenAPI as well.

[GitHub30]

thx

[intotecho]

I need to rollback but I cant find version 2.x of swagger-editor-dist.

[andy-maier]

+1 for a resolution to this issue. It prevents using v3 of the editor for larger projects.

[CameronGo]

+1 - this is kind of a big deal to me as well

[arlix85]

+1 same for me, our team is fine with the portability of the online editor, but we're still forced to use v2 editor because of this...

[giuliana-bezerra]

Same for me, I need relative paths in documents because there's distinct enviroments hosting Swagger-editor (i.e., distinct URLs).

[sprelacart]

+1 for a fix of this issue.Without references to local schema files we need to look around for another tool :(

[liam-donohoe]

+1 - V2 only viable option for real world API development that leverages common schema definitions in separate file(s). Very disappointing.

[jorgii]

+1 would love to use it as well.

[zbajbutovic]

Could you update what's the status of this PR? We externalized definitions in yams files, and couldn't reference them in any swagger-editor V 3 (the latest tried 3..5.1) using relative paths that we are able to resolve in V 2 (e.g. $ref: './external.yaml#someDef'). It's a major roadblock for us to move to V 3

[webron]

This is not a PR, it's a feature request. At the moment, we're not doing any active work on supporting it, but we might in the future.

[zbajbutovic]

Thanks Ron. Would you be able to prioritize it? Based on the posting it is blocking many people working on real world enterprise implementations to move to V 3.

[webron]

Unfortunately, given the work load that we have - I can't prioritize it at the moment. I'm sure this is not what you'd want to hear, but there is a solution we provide as a company in our commercial tool (whether free or paid versions).

This is not to say that that's the reason this is not being implemented here. The way it's implemented there is very different than what we could just migrate to the open source, otherwise we would have done it by now. We have limited resources and our to do list is (very) long - someone's going to not be happy with the results eventually. As stated above though, we'd review related PRs should anyone submit them.

[xhanka00]

I know it's getting a bit annoying... but +1 here as well.

[jemerald]

Not 100% sure what the complain is, the latest 3.5.2 swagger editor DO support external JSON reference. Even works with the online version, using the following URL:

http://editor.swagger.io/?url=http://localhost:8080/specs/a.yaml

The local setup is a simple NodeJS express server serving content from a folder, with CORS middleware to allow access from editor.swagger.io

We don't usually use the online editor, instead, we run a local copy hosted on the same express server. The local copy uses the swagger-editor-dist package and a custom index.html page, which adds an extra plug-in to save the changes from editor via HTTP (e.g. PUT /specs/a.yaml).

For the extra plug-in, see my reply on https://github.com/swagger-api/swagger-editor/issues/1241#issuecomment-342695807

[ghost]

+1

It can be reproduced on both swagger.io editor and ui with the following Spec:

https://forge.etsi.org/rep/gitweb.cgi/NFV-SOL002-SOL003.git/blob_plain/HEAD:/src/SOL003/VNFLifecycleManagement/VNFLifecycleManagement.yaml

If I understand correctly the loader within Swagger-UI should be configured with the right value of basePath by the Editor.

Maybe this could be done using the loaded url and stripping of the latest segment?

[micbra]

Any updates on this? This issue is around for over one year now and hasn't been approached yet. Not being able to reference relative paths i.e. organizing the config into multiple files, is a massive drawback for me and my team.

[jemerald]

@carignani You need to open the editor with url query parameter, like this:

http://editor.swagger.io/?url=https://forge.etsi.org/rep/gitweb.cgi/NFV-SOL002-SOL003.git/blob_plain/HEAD:/src/SOL003/VNFLifecycleManagement/VNFLifecycleManagement.yaml

I have tried the above and the relative file references are loaded properly as you expand the method in swagger UI, see screenshot of the network traffic:

Note: the 404 error is caused by a bad reference in SOL002SOL003_resp.yaml line 95 (extra slash at the beginning):

      $ref: "/../definitions/SOL002SOL003_def.yaml#/definitions/ProblemDetails"

[SuryanathanP]

+1

This should be a bug. $ref is supported in the 3.0 spec.

[obstschale]

+1

I just started describing my API with OpenAPI and I encoutered this bug. IMHO, if this worked in v2 it is a bug in v3. Please fix it. I want to use this feature. :)