Regression: Redocusaurus can no longer load OpenAPI/Swagger 2.0 definitions

[markcarroll]

Version 0.4.6 successfully loads and displays OpenAPI/Swagger v2.0 documents, but upgrading to v0.5 now returns an error:

    Error: Document must be valid OpenAPI 3.0.0 definition

Reverted to 0.4.6 and it works again.

[rohit-gohri]

Might be related to Redocly/redoc#1724

Does your spec define a top level field swagger: "2.0"?

[markcarroll]

Yes it does. Mark On Nov 30, 2021, at 8:11 PM, Rohit Gohri ***@***.***> wrote:  Might be related to Redocly/redoc#1724 Does your spec define a top level field swagger: "2.0"? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[joshuaflanagan]

Might be related to Redocly/redoc#1724

It is not - in that issue, the reporter had an invalid spec (version specified as an integer instead of a string).

I tested and verified that redoc-cli can properly load Swagger 2.0 files. However, it does report that it converts the file to 3.0 first:

[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0

which I've tracked down to the loadAndBundleSpec utility function in redoc.

It seems like redocusaurus might be initiating redoc in a way that bypasses that conversion.

I see the same error when specifying a swagger 2.0 file in JSON format using the spec option.

[rohit-gohri]

@joshuaflanagan Thanks for tracking it down! It seems they are using this function in StoreBuilder : https://github.com/Redocly/redoc/blob/6c7685e5fa04314328a445d7077600692c49489c/src/components/StoreBuilder.ts

If we switch to using StoreBuilder too for creating the AppStore here:

redocusaurus/packages/docusaurus-theme-redoc/src/theme/Redoc/Redoc.tsx

Lines 21 to 28 in 4875be7

	const store = useMemo(() => {
	if (!spec) return null;
	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	return new AppStore(spec as any, specUrl, {
	...redocOptions,
	theme,
	});
	}, [spec, specUrl, redocOptions, theme]);

Then this will solve both this and #80 I think.

[rohit-gohri]

I have released a beta for v1 where this is fixed: #146

It has some breaking changes (mostly simplification of option names). New docs are at https://redocusaurus-v1.vercel.app/docs

It will be great if you could try it and give some feedback.

[joshuaflanagan]

I am trying to test it, but am running into errors. However, it is difficult to tell the source, since I am also attempting to update my version of docusaurus at the same time. If you tell me the exact version of docusaurus that you are testing on and expect to support, I can use the same. They have been releasing a lot of betas recently which can add to the confusion.

[joshuaflanagan]

To be clear, in my package.json I have:

  "@docusaurus/core": "^2.0.0-beta.17",
  "redocusaurus": "0.0.0-beta-20220314034003",

My attempt at running docusaurus build results in:

[INFO] [en] Creating an optimized production build...
[ERROR] Unable to build website for locale en.
[ERROR] ValidationError: "layout" is not allowed

This appears to be referring to the spec definition in the redocusaurus config of docusaurus.config.js.

My specs config looks like:

  [{
    routePath: 'myservice/api',
    spec: 'myservice/api.yaml',
    layout: { title: 'Service API' }
  }]

When I delete the layout config line, I now get:

[INFO] [en] Creating an optimized production build...
[ERROR] Unable to build website for locale en.
[ERROR] ValidationError: "debug" is not allowed

I don't specify debug anywhere. I also noticed that if I change routePath to route (which the docs suggest) I get [ERROR] ValidationError: "route" is not allowed.

[rohit-gohri]

Thanks for testing it out. Regarding beta, beta.17 is what is supported and what I'm using too.

And you are on the correct version of redocusaurus but my build was wrong. I just released a new version (from the latest commit) : 1.0.0-beta-20220315043813.

Verified the dist files on unpkg and tested it on a fresh project. It should be working now

[joshuaflanagan]

Thanks - that fixed it, I was able to get a successful build! I'll do more thorough testing tomorrow.

[joshuaflanagan]

This build is working for me and resolves this issue.

[rohit-gohri]

Awesome! Thanks for testing it out.

There are some minor styling changes compared to v0 (see percy diff). I know the fix for most of those, so I'll release stable v1 once they are fixed.