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.
#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.

[CharlieReitzel]

@jemerald wrote:

I've created a repo to demo my setup of locally hosted swagger editor:
https://github.com/jemerald/swagger-local-editor

Thanks for that. It works well. Nice clean bit of code.

To get it to work with my own files, I renamed your specs directory to specs.demo and created a symbolic link named specs, but pointing at my own source directory. Worked fine. Ideally, you might provide a --specs-directory startup parameter that you could map the the /specs/* URL path. Just a thought. Cheers.

[webron]

FWIW, we'd be happy to accept a PR to re-add the functionality.

[jemerald]

@jemerald wrote:

I've created a repo to demo my setup of locally hosted swagger editor:
https://github.com/jemerald/swagger-local-editor

Thanks for that. It works well. Nice clean bit of code.

To get it to work with my own files, I renamed your specs directory to specs.demo and created a symbolic link named specs, but pointing at my own source directory. Worked fine. Ideally, you might provide a --specs-directory startup parameter that you could map the the /specs/* URL path. Just a thought. Cheers.

Good idea @CharlieReitzel , although the project is really just a demo on how to setup an local editor environment, and to demo that the editor actually do support JSON references across files (which is what the OP is about).

Feel free to adopt it for your needs. 😃

[adzeeman]

It seems that activity in the open issue has stopped. Has any progress been made on this issue to support a relative schema?

As many have mentioned, this is a significant blocker for adopting v3 of the OpenAPI specifications.

The official swagger specifications seem to allow the referencing of components from external files:

[lud-hu]

I'm now successfully using swagger-ui-watcher for this. :)

[saulonunesdev]

Hi,

I don't know if helps, but i resolved this issue by doing this changes:

• docker-compose

  swagger-editor:
    image: swaggerapi/swagger-editor
    container_name: "swagger-editor"
    ports:
       - "8081:8080"
    volumes:
      - ./docker/swagger:/usr/share/nginx/html/docs
    environment:
      URL: /docs/main.yml

• main.yml

openapi: 3.0.0
info:
  title: Server API
  description: API Documentation for Server.
  version: 1.0.0
servers:
  - url: 'http://localhost:8000/api/v1/'
    description: Local Server
  - url: 'http://staging.server.com/api/v1'
    description: Staging Server
paths:
  /login:
    $ref: 'session.yml#/login'

• session.yml

login:
  post:
    summary: Authenticate User
    description: Authenticate User
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 1
        email:
          description: User Email
          type: string
          format: email
          example: example@mail.com
        password:
          type: string
          writeOnly: true
          example: 1
      required:
        - email
        - password

url that i use to go directly to the main.yml: http://localhost:8081/?url=/docs/main.yml
All .yml files are inside ./docker/swagger

[eMarek]

I receive the same error when I try to reference another file:

Resolver error at paths./partner/{partnerId}.get.responses.200.content.application/json.schema.$ref
Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: 'schemas/partners/Partner.schema.json' basePath: 'undefined'

I tried everything I found on internet but could not get it working.

[xmyLydia]

@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.

This is very useful, after installation according to the README.MD, you just need to run
swagger-ui-watcher path/to/swagger/folder/swagger.yaml, then in http://127.0.0.1:8000/ there will be output.

[akopchinskiy]

It's still doesn't work.

[tgiardina]

I'm commenting because this is the first thing that pops up when I Google "Tried to resolve a relative URL, without having a basePath." and I think it deserves a clear summary.

There are two problems being discussed in this issue:

1. How do I resolve my base path with Swagger Editor?
2. Can I set my base path through the Swagger Editor UI?

@jemerald provided a great answer to 1 here! The answer to 2 is no, this is an open feature request.

I suggest that this issue be closed since Problem 1 has been resolved. Then someone can open up a new issue specifically re Problem 2 without all the noise surrounding Problem 1.

If I misunderstood what's going on here, let me know and I will delete/edit this comment!

[CharlieReitzel]

@tgiardina wrote:

I'm commenting because this is the first thing that pops up when I Google "Tried to resolve a relative URL, without having a basePath." and I think it deserves a clear summary.

Defintely helpful.

There are two problems being discussed in this issue:

1. How do I resolve my base path with Swagger Editor?
2. Can I set my base path through the Swagger Editor UI?

I'd suggest a 3rd issue: relative URLs should "just work" relative to the primary document as described here:
https://tools.ietf.org/html/rfc3986#section-5.4

It's should not be necessary to host swagger-editor in a Node server to make this work. Javascript is fully capable of resolving relative URLs.

[mat813]

Well, thing is, there was an issue on swagger-ui, there swagger-api/swagger-ui#2746, it was closed and locked with a simple message saying "this was fixed" but, well, it is three and a half years after the "this was fixed" message, and I spent about an hour trying to figure out how it was fixed, like, going through all the commits between the issue being created and the "it was fixed" message, in multiple swagger-* repositories, and well, it seems it is not fixed.

[chuve]

I resolved the issue in by resolved references ($ref) in spec first before provide it to Swagger-UI. Here is the repo shows how to do it - https://github.com/chuve/swagger-multi-file-spec
Hope it will be useful someone and save time.

[faelin]

Years later, this still remains an open issue!

[prashantnirgun]

Resolved n close it

[faelin]

@prashantnirgun then can we close this issue? This actual issue is not yet closed, and there is no documented solution that I have found; I just encountered this issue yesterday when using the editor.swagger.io service

[elizatlawy]

Any news regarding solving this issue? I'm having the same problem 6 years later.

[chuve]

Any news regarding solving this issue? I'm having the same problem 6 years later.

Check the comment above - #1409 (comment)
It is one of the ways how to resolve $refs on the fly and use a composed yaml file.

[elizatlawy]

I was able to use Solve it by using the swagger-cli and bundle the main file to resolve the $refs as following: swagger-cli bundle ./src/docs/apiDoc.json --outfile ./src/docs/apiDocBundle.json

[danielschilling-ml]

@Yelfive how do you open the editor and point it to your spec?

The editor has a url query parameter allowing you to specify it. Since your spec is hosted on the same server, you just need path like this:

http://myserver/editor/?url=/spec/myspec.yaml

then in your /spec/myspec.yaml you should be able to $ref with relative path

I want to try to add some visibility to @jemerald's awesome comment from 2019. Swagger Editor is actually capable of doing this! You have to point the editor at your openapi file by adding a ?url={YOUR_URL_HERE} query string. After that, Swagger Editor has no problem handling remote references - properly using the url parameter to resolve any relative urls.