Migrate ReDoc to React

[RomanHotsiy]

Hey, ReDoc community!

To support OpenAPI 3.0 I am working on a major refactor of the codebase. As part of this refactor I am considering rewriting ReDoc view layer completely to React.

Why?
I've been working with React on a few side project for the last 5-6 month and I really loved working with it comparing to Angular:

• much much simpler, no magic
• more performant (especially since React 16 release aka Fiber)
• the community is healthier - much more stable ready-to use modules (there are lots in Angular too, but usually they are part of some huge UI-packs)
• smaller bundle size
• simpler to build-in live updates
• server-side rendering actually working
• I love styled-components

Also, I often hear in the issues or PRs that "I don't know Angular but I will try". Probably React can lower the barrier for new contributors.

I will try to achieve fully backward compatibility with the Angular version.

Now I want to hear the voice of community!
What do you think? Do you find this idea is good or bad! Any concerns! Or just vote 👍 or 👎

Thanks in advance!

cc contributors (sorry for bothering): @bfirsh @brendo @adamaltman @cesarlevel @IvanGoncharov @amanganiello @kedashoe @alairock @Joe-noh @gierschv @jsmartfo @jaingaurav @agallou @jacobbaskin @MikeRalphson @bennyn @adamd @LeFnord @wilsonge @philsturgeon @khorolets @pgolm @jfeltesse-mdsol @Alfaspider @oblakeerickson @Jean-Daniel @KtorZ @jimmyjames @bioball

[khorolets]

I can't in Angular, so React sounds perfect 👍

[avkonst]

Coming from server side development background, I can understand JavaScript code only if it is written in typescript :) any framework is fine if app's code is in typescript, but I do not know if react is good with typescript?

[ghost]

Yes , typescript with react is the best. Here there is a starter guide: https://www.typescriptlang.org/docs/handbook/react-&-webpack.html

[RomanHotsiy]

@avkonst yes, react is pretty good with typescript!

[brendo]

Hey @RomanGotsiy, thanks for the ping. Without shamelessly plugging, that's exactly what we did at my company, we created Lincoln, which we've credited to ReDoc as inspiration.

We enjoyed the experience working with React, and found it easier to get started because we had readily available resources in house with React knowledge.

[philsturgeon]

I'm entirely useless at Angular, but only bloody awful at React. Big improvement for me, happy to see it coming.

[jsmartfo]

👍 yes from me!!

[j26nz]

@RomanGotsiy any time frame for this? would like to help. Thanks.

[KtorZ]

From an external point of view, React seems to be of broader acceptance in the open-source community. I still think Angular has good traction on the enterprise side yet, I believe they're less people in the Angular community likely to contribute than in the React one.

Both frameworks are capable of achieving the same though. If you feel comfortable enough with React, then go for it ^.^

[erlend-sh]

Does this mean you might also revisit the idea of basing the rewrite on Gatsby?

You would get a lot of amazing things for free:

• PWA
• offline
• GraphQL
• PRPL pattern

[j26nz]

Hey @RomanGotsiy any timeframe for this before you make the repo public and open some tickets for us to start contributing ? Thanks.

[RomanHotsiy]

Hey @j26nz,

Thank you! I am very close. Hopefully, I will publish something to branch till the end of the week.

[sudsk]

@RomanGotsiy - is the first react version for OpenAPI 2.0 or will it support 3.0 too?
Thanks for the great work!

[RomanHotsiy]

@suds123 Will support OpenAPI 3.0 + OpenAPI 2.0 via converting it to OpenAPI 3.0

[RomanHotsiy]

@suds123 but it won't support all the OpenAPI 3.0 for now, just some subset (basically all the corresponding OpenAPI 2 features + oneOf). E.g. it won't support static hypermedia (aka Links), complex parameters details, etc.
We'll add these later

[RomanHotsiy]

Hey, everybody,
wanted to share an update on the progress!

It takes me more time than I expected but I'm really close to publishing the first alpha release.

Here is what's already done (+sneak peek 🎥):

• left menu (including headings from markdown)

• navigation + hash navigation working

• middle panel (almost) ready (schema component, responses)
  

• oneOf support 🎉
  

Todo

• Finish middle panel (styling, some fixes)
• Implement RIght panel (should be not difficult)
• Search (probably will be missing in the first alpha)

Thanks everyone for patience! I see ReDoc community is excited about this rewrite and this keeps me motivated. Special thanks go to @philsturgeon for his awesome article covering ReDoc.

btw, I've set up a newsletter for ReDoc updates and changelog: http://eepurl.com/c4RsdH.
It may be a better alternative than GitHub emails 👋

[bennycode]

This is nuts!! Thanks for sharing with us. Keep up the great work! 👏👏👏

[RomanHotsiy]

@shenghu, @zufrizalyordan sorry for long reply, I've been traveling whole last week.

This PR is WIP. This is not alpha release, just a dump of the progress with the rewrite. spec-url and <redoc> tag are just not implemented yet. They will be ready for the first alpha release.

[j26nz]

@RomanGotsiy - Is it possible to use this in a react app? using bundle.js somehow?

[RomanHotsiy]

Hey everybody 🙌 !
The last month was pretty busy for me so I have very little progress with this :(

But I finally can again concentrate on ReDoc 🎉 ! So I will try my best to release proper alpha version until the end of the next week!

Thanks everybody for being patient! Stay tuned!

@j26nz not yet, unfortunately, will be possible once I'm done with alpha.

[j26nz]

@RomanGotsiy I can see the progress and it's creating bundle and spec-url is back 😄 keep up the good work mate ! Will it be possible to send the spec (yaml definition) instead of url in alpha release ? Our API return data in swagger - we want to change swagger dynamically. Any suggestions?

[SebastianStehle]

It would be awesome if you could go over the issues and label the issues that will be addressed with this rewrite.

[RomanHotsiy]

@j26nz thanks for kind words! I'm really really close to the alpha!

Will it be possible to send the spec (yaml definition) instead of url in alpha release?

Sure it will be possible. Same as it worked before, you'll be able to pass it to Redoc.init using ReDoc standalone bundle. Or you'll be able to pass it as a React component props if using it as a lib.

@SebastianStehle yep, this makes a lot of sense! Will definitely do once release the alpha.

[sudsk]

@RomanGotsiy - I just did a try of building and launching the app and it works great! I had the app started on http://localhost:9090.
I have a question - does it build a bundle.js somewhere and can I use it as a standalone self-contained js just like redoc.min.js and render it through gh-pages?

[RomanHotsiy]

@suds123 yes, indeed!
Just run npm run bundle and you'll find redoc.standalone.js in bundles folder.
The old way to setup should work (i.e. using <redoc> tag).

P.S. Also, it already supports both OpenAPI 2 and OpenAPI 3. OpenAPI 2 is converted to OpenAPI 3 so you can improve perf a bit by converting it ahead of time using converter by @MikeRalphson (which is used internally by ReDoc btw)

[sudsk]

@RomanGotsiy - Thanks! I'll try that. Last time I just did a yarn install and npm start, and it started app on http://localhost:9090.

[sudsk]

@RomanGotsiy - Yes it works! Thanks!

[alexjomin]

Hi there !

Thank you for your awesome work !

I tried to pull the new commits and I'm getting the following error : (I have no error on the http://editor.swagger.io/, and the previous version was ok)

Unhandled Rejection (TypeError): Cannot read property 'schema' of undefined
children
./src/components/Responses/Response.tsx:50:20
  47 |     </UnderlinedHeader>
  48 |   )}
  49 | >
> 50 |   {({ schema }) => {
     |      ^  51 |     return <Schema skipWriteOnly={true} key="schema" schema={schema} />;
  52 |   }}
  53 | </MediaTypesSwitch>
View compiled
t.render
./src/components/MediaTypeSwitch/MediaTypesSwitch.tsx:43:20
  40 |         options,
  41 |         onChange: this.switchMedia,
  42 |       })}
> 43 |       {this.props.children(content.active)}
     |                  ^  44 |     </div>
  45 |   );
  46 | }

[RomanHotsiy]

@alexjomin pull the latest changes and try again. It should work now.
In case this doesn't work, provide me with your spec or minimal reproducible sample so I can reproduce.
Thanks

[alexjomin]

@RomanGotsiy That's fine now ! thank you

[shreyas-agnihotri]

@RomanGotsiy Do you think the alpha will be ready by early December? Eagerly waiting.. :-)

[RomanHotsiy]

It is ready today 🎉 🎉 🎉 😌

Just created tag v2.0.0-alpha.1 and it was just pushed to npm by Travis CI!

Changelog here: CHANGELOG.md
Updated Readme with docs here: Readme

All the alpha releases will be tagged with next tag on npm so you can install them with the following command:

npm install redoc@next

I haven't created demo yet, though. Will work on this on weekends!

I didn't spend so much time on updating docs 📝 so any feedback/help with clarifying them would be appreciated! 🙇

Let's report all the related issues in a separate issue to not make so much noise here.

Also, On weekends I will try create CONTRIBUTING.md and will create separate issues with help wanted badge so it would be simpler to start contributing!

[RomanHotsiy]

I've just quickly hacked up an example of using ReDoc as a React Component with create-react-app.
Here it is: https://github.com/APIs-guru/create-react-app-redoc

And here are only changes required to install and use ReDoc: Redocly/create-react-app-redoc@da80371

[runes83]

Hello @RomanGotsiy,

Any update on the move to react?

[wopian]

@runes83 its being actively worked on over in #357 👍

[RomanHotsiy]

I think this can be closed already 😃

[pvs1]

I have a bulky swagger.json and the page takes forever to load with Redoc standalone . Is there a way to get around it?
Appreciate any input in advance.
Thanks

[adamaltman]

@pvs1 we're sorry... we don't have a free open source version that will do that. We do have a paid version which has further performance enhancements. If you are interested, you can try it out for a free trial. You can reach us via the email at the bottom of https://redoc.ly