Incorrect $ref resolution

[jebertz]

$refs are resolved using the relative path from where rdme is run, not the relative path to the referring document as it is specified in https://spec.openapis.org/oas/v3.1.0#relativeReferencesURI. This is causing a lot of issues in our ability to automate.

[kanadgupta]

Hi @jebertz!

By default, we require references from the root of the directory. Relative references are supported via the workingDirectory argument. A couple questions:

1. Have you tried using the workingDirectory argument?
2. If so, mind elaborating on your automation setup? Are you using a CI environment like GitHub Actions or CircleCI?

And thanks for pointing out that language in the spec, I wasn't aware of that. We're working towards a v9 release and we're hoping to deprecate the workingDirectory flag since it's proven to be an issue in certain CI environments. We rely on json-schema-ref-parser for resolving $ref pointers so this is a tricky problem for us. It looks like the latest release includes APIDevTools/json-schema-ref-parser#305 which might be helpful here. Will look into this further with @erunion once he's back.

Thanks!

Tagging a few potentially related issues below for posterity:

APIDevTools/json-schema-ref-parser#199
APIDevTools/json-schema-ref-parser#251

[jebertz]

Thank you for the quick response. We had tried workingDirectory, but were apparently using it incorrectly on the first try. After your message, we tried the workingDirectory again and got it working this time, so thank you!

If it's helpful to you for future designs, we're trying to run the validate as a job in github actions on PR/push for any files that changed and then run sync on merge. We very heavily use $refs and are also only trying to lint one directory (we have the OAS for internal, our legacy external - v2, and our new external - v3 in one repo and only want to validate the v3). We are also using spectral and were evaluating a few other tools as well that expected the refs to be relative (which was why we didn't just change them). Thanks again!

[kanadgupta]

@jebertz great to hear that the workingDirectory flag was working for you! Out of curiosity, were you able to get the flag working properly in GitHub Actions? If so, we'd love to learn more about your setup — we've had some issues getting that flag working properly in CI environments and I'd love to see what you did!

[jebertz]

We were only trying to do this for our public v3 endpoints, and they're all in a single directory (with common files elsewhere). I think if we wanted to do multiple directories the simplest thing would probably to re-do this whole flow per-directory. It's a little hard code-y, but this should almost never change, so not a big deal. We did:

name: ReadMe validate

on:
  pull_request:
    branches:
      - main

jobs:
  rdme-openapi-validate:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed-oas-files
        uses: tj-actions/changed-files@v39
        with:
          files: external-v3/webadmin*

      - name: Install dependencies
        if: ${{ steps.changed-oas-files.outputs.any_changed == 'true' }}
        uses: ./.github/workflows/actions/install-dependencies

      - name: Rdme validate for every changed file
        if: ${{ steps.changed-oas-files.outputs.any_changed == 'true' }}
        shell: bash
        run: |
          for file in ${{ steps.changed-oas-files.outputs.all_changed_files }}; do
            npx rdme openapi:validate $(echo "$file" | cut -d/ -f3) --workingDirectory=external-v3/webadmin
          done

I guess we're struggling with the syncing due to things related to the ID as mentioned in that other issue.

[kanadgupta]

Got it, thanks for sending that across! I'm going to close this out since it appears this specific issue around $ref resolution is resolved, but feel free to open up more issues as you run into them.

[jebertz]

thank you!