Can't upload OAS file

[andrefpoliveira]

Today, while trying to update the documentation, I got the following error:

npx --yes rdme@v10 openapi upload ./docs/category.json --key=[MASKED] --slug=category
- Validating the API definition located at ./docs/category.json...
Cannot read properties of null (reading '$ref')

This command worked on the 8th of July and the current changes are just simples strings. I didn't change any reference.
How should I fix it? Or even find where the mistake is?

Uploading the file directly in the dashboard worked fine...

[tyler-hagen]

I'm pinned to major version 9 and I'm having the same issue even with the old interface (haven't migrated to readmeio refactored yet)

[tyler-hagen]

@andrefpoliveira pinning to the patch version 9.2.1 (instead of using 9.2.2) fixed the issue for me. Maybe try going back a patch version on 10 and see if that works for now?

[cristiadu]

Also affecting me and I didnt change the version, so this is odd. Happening on 10.3.0 and 10.4.0 for me, will check another earlier version

[cristiadu]

Still having this issue with 10.2.0 as well. I guess I can try 10.0.0 but seems like an issue regardless of the version

[erunion]

Are either of you able to share the OpenAPI definition that's triggering this?

And how are you also installing rdme? Globally or locally within your repository? For either can you run npm ls @apidevtools/json-schema-ref-parser oas-normalize? Our dependency on @apidevtools/json-schema-ref-parser in oas-normalize was updated a patch release yesterday that should have been safe, so maybe there's a regression there. Believe we've seen issues in the past with our oas library in the past where minor and patch releases there get pulled into new rdme installs without us releasing a new rdme build.

[cristiadu]

I'm using rdme only on the CI and installing from there, something like:

      - name: Install Readme.io CLI
        run: pnpm install -g rdme@${{ env.RDME_CLI_VERSION }}

RDME_CLI_VERSION is set at the root, I tested 10.4.0, 10.3.0, and 10.2.0. Didnt test older versions as apparently the flow changes a bit and I would require changing my code.

That's how I upload:

      - name: Upload Internal API Documentation
        id: upload-internal
        run: |
          echo "Uploading internal API documentation with restricted visibility..."
          rdme openapi upload \
            --key=${{ secrets.README_API_KEY }} \
            --useSpecVersion \
            "${{ env.INTERNAL_SPEC }}" 2> internal_error.log
          echo "Internal API documentation upload completed"

I checked the file and api keys are in place, cannot really share the spec yet as we haven't defined all public vs private APIs, I did see we had $ref without single quotes on the references, but adjusting that didnt change anything.

This was working before with the 10.3.0 version, so my guess is that something the version uses (readme API?) possibly changed something on how the upload goes?

The file I'm trying to upload is a merged api-spec based off multiple other ones, the validation passes on both rdme and redocly (we use it for the merging flow).

[cristiadu]

The result of the command you said to try:

❯ npm ls @apidevtools/json-schema-ref-parser oas-normalize 
@giftbit/redacted@0.1.0 /Users/cristianofaustino/projects/redacted
└─┬ rdme@10.4.0 -> ./node_modules/.pnpm/rdme@10.4.0/node_modules/rdme
  ├─┬ oas-normalize@14.1.1 -> ./node_modules/.pnpm/oas-normalize@14.1.1/node_modules/oas-normalize
  │ └─┬ @readme/openapi-parser@4.1.1 -> ./node_modules/.pnpm/@readme+openapi-parser@4.1.1_openapi-types@12.1.3/node_modules/@readme/openapi-parser
  │   └── @apidevtools/json-schema-ref-parser@14.1.0 -> ./node_modules/.pnpm/@apidevtools+json-schema-ref-parser@14.1.0/node_modules/@apidevtools/json-schema-ref-parser
  └─┬ oas@27.2.0 -> ./node_modules/.pnpm/oas@27.2.0/node_modules/oas
    └─┬ @readme/openapi-parser@4.1.1 -> ./node_modules/.pnpm/@readme+openapi-parser@4.1.1_openapi-types@12.1.3/node_modules/@readme/openapi-parser
      └── @apidevtools/json-schema-ref-parser@14.1.0 deduped -> ./node_modules/.pnpm/@apidevtools+json-schema-ref-parser@14.1.0/node_modules/@apidevtools/json-schema-ref-parser

[cristiadu]

looking at the libraries you mentioned the upgrade, I think it might've been caused by this:

APIDevTools/json-schema-ref-parser#391

It changes behavior exactly around the $ref parsing, and exactly around the same date @andrefpoliveira mentioned.

[erunion]

I've just rolled back the @apidevtools/json-schema-ref-parser bump in @readme/openapi-parser over in readmeio/oas#987 and published some new patch releases. You may need to clear your NPM caches but v13.0.5 of @apidevtools/json-schema-ref-parser should be used now.

Will see if I can figure out what exactly broke upstream and @kanadgupta and I will work to ensure this doesn't happen again.