Migrate ReDoc to React

Question

Migrate ReDoc to React

RomanHotsiy opened this issue 7 years ago · 56 comments

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

Answer 1 · 2017-08-17T09:17:37.000Z

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

Answer 2 · 2017-08-17T09:26:12.000Z

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?

Answer 3 · 2017-08-17T09:28:35.000Z

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

Answer 4 · 2017-08-17T09:29:00.000Z

@avkonst yes, react is pretty good with typescript!

Answer 5 · 2017-08-18T02:33:45.000Z

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.

Answer 6 · 2017-08-19T11:51:46.000Z

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

Answer 7 · 2017-08-19T14:24:08.000Z

👍 yes from me!!

Answer 8 · 2017-08-21T22:56:55.000Z

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

Answer 9 · 2017-08-22T08:16:45.000Z

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

Answer 10 · 2017-09-09T00:17:38.000Z

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

Answer 11 · 2017-09-18T22:50:49.000Z

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

Answer 12 · 2017-09-19T04:54:54.000Z

Hey @j26nz,

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

Answer 13 · 2017-09-19T14:55:50.000Z

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

Answer 14 · 2017-09-19T15:00:46.000Z

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

Answer 15 · 2017-09-19T15:05:30.000Z

@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

Answer 16 · 2017-09-26T09:02:11.000Z

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 👋

Answer 17 · 2017-09-26T09:06:22.000Z

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

Answer 18 · 2017-09-26T12:15:17.000Z

Yaaaaay! Awesome work, and the new functionality looks amazing. That oneOf is going to be a big deal.

Answer 19 · 2017-09-26T23:22:21.000Z

I'm not really a fan of React – prefer Vue.js – … but yeah, respect awesome work 👍
and many thanks for it 😄

Answer 20 · 2017-09-28T12:51:54.000Z

@RomanGotsiy - any news about alpha release? Thanks!

Answer 21 · 2017-10-02T05:58:46.000Z

@suds123 I was pretty busy last week with other projects so didn't have a chance to work on ReDoc rewrite 😞
Going to continue today

Answer 22 · 2017-10-05T17:01:04.000Z

From #312 it seems like this change will have OpenAPI 3.0 support built in as well? Just wanted to make sure and see if that was the case or not. Thanks for all the hard work and look forward to an initial release!

Answer 23 · 2017-10-09T03:03:21.000Z

@RomanGotsiy we are using openapi 3.0 to describe our API and use redoc to render the API documentation. I'm very looking forward to see ReDoc to support openapi 3.0 asap.

Answer 24 · 2017-10-09T21:49:17.000Z

Hi @RomanGotsiy - is there an alpha release coming soon for openapi 3.0 support? Thanks!

Answer 25 · 2017-10-10T06:18:42.000Z

@RomanGotsiy do I need to make any changes to swagger2openapi for the cases where the input definition is valid but conversion from 2.0 to 3.0.x is not lossless? This mainly involves invalid parameter in and collectionFormat combinations. The converter currently throws in these situations.

Happy to add an option to make a best-case conversion, possibly adding a specification extension so you can show a tool-tip etc?

Answer 26 · 2017-10-10T07:28:25.000Z

@suds123 new ReDoc will be based primarily on openapi 3.0 and will support openapi 2 via conversion. The initial version is coming tomorrow (or 1 day after max).

@MikeRalphson yes, it would be great if there was some option to not throw. Will reach you using DM to discuss.
Thanks!

Answer 27 · 2017-10-11T21:25:54.000Z

Hey 🙌 ,

I've finally pushed my WIP work and created a PR: #357.

Don't try reviewing this PR on GitHub :)

There are some details in PR description.
Unfortunately, this is not alpha release yet though 😢. I overestimated my abilities.

But you can already try and feel it. Also, you can try with your spec (will need converting to openapi3 though, as I haven't built the converter in yet).

Also, it would be great if anybody can review the code in general!

I am taking 1-2 days break as I've been working on this 13 hours a day during last 3 days. I have to rest a bit!

Answer 28 · 2017-10-11T21:34:50.000Z

Online converter here while @RomanGotsiy gets some well-earned rest!

Answer 29 · 2017-10-12T01:59:55.000Z

@RomanGotsiy well done mate ! Thanks for putting it out. It looks good.

Answer 30 · 2017-10-12T04:06:36.000Z

@RomanGotsiy this is awesome, I just pulled and ran locally it seems really responsive... nice work!

Answer 31 · 2017-10-13T05:53:41.000Z

I tried the PR out with a fairly large and complex spec and it did surprisingly well after resolving it to a single file. It felt really fast and responsive to use. Great job so far! 👍

I thought to share a few issues that I noticed. Didn't feel like creating full blown issues as this is indeed work very much in progress.

Refs to paths like paths.yaml#/paths/~1foos~1{foo_id} don't seem to work and cause "invalid reference token" error. However, paths.yaml#/paths/~1foos works just fine. Might be the curly braces?
Examples for properties are shown always as strings, so examples of string properties appear escaped, e.g. "\"example value\""
oneOf and anyOf seem to work, but when they are part of allOf, others are ignored.

allOf:
  - oneOf:
    - $ref: ... # these two are
    - $ref: ... # shown in tabs
  - type: object # this is ignored
    properties:
      foo:
        type: string

With a very basic API, the right pane stayed stationary and didn't move with the dark gray background when resizing the browser window with Chrome (didn't test other browsers). This didn't happen with the complex API or Petstore example.

I can provide additional details if necessary.

All in all, those issues are minor or appear in quite advanced usage, so the progress is fantastic so far. Thanks for all the great work @RomanGotsiy !

Answer 32 · 2017-10-13T14:21:50.000Z

@mikunn, thanks for checking this out and reporting the issues.
While some are pretty obvious, the 1st and the third one require more details to reproduce.
Would be great if you DM me on twitter (@RomanHotsiy) to discuss that and not distract folks subscribed to this issue!

Answer 33 · 2017-10-16T09:04:07.000Z

@RomanGotsiy I created a Twitter account (@mikunnas), but can't send you a DM as you are not following me (or I don't know how to use Twitter :). I follow you so please send me a message. I have small examples ready to demonstrate the issues.

Answer 34 · 2017-10-17T04:09:41.000Z

@RomanGotsiy I tried to use the built bundles and found that in <redoc id="example" spec-url=""/>

id='example' is required now.
spec-url is not respected. It is hard-coded to be swagger.yaml

Also in lib/index.html, it use this style <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">. I hope this dependency can be removed as *.googleapis.com is not available from China.

Answer 35 · 2017-10-18T08:19:50.000Z

Hi Roman, same as shenghu.
In older version of ReDoc, we can re-init to load a new swagger spec.
Is it possible to pass props to load another swagger spec?

Answer 36 · 2017-10-22T13:09:21.000Z

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

Answer 37 · 2017-11-01T02:15:29.000Z

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

Answer 38 · 2017-11-10T11:07:36.000Z

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.

Answer 39 · 2017-11-19T21:53:38.000Z

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

Answer 40 · 2017-11-19T22:02:17.000Z

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

Answer 41 · 2017-11-19T22:06:04.000Z

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

Answer 42 · 2017-11-20T20:34:07.000Z

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

Answer 43 · 2017-11-20T20:40:17.000Z

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

Answer 44 · 2017-11-20T20:44:09.000Z

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

Answer 45 · 2017-11-20T20:47:39.000Z

@RomanGotsiy - Yes it works! Thanks!

Answer 46 · 2017-11-21T14:08:55.000Z

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 | }

Answer 47 · 2017-11-21T14:44:54.000Z

@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

Answer 48 · 2017-11-21T15:16:52.000Z

@RomanGotsiy That's fine now ! thank you

Answer 49 · 2017-11-23T03:15:01.000Z

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

Answer 50 · 2017-11-23T10:43:25.000Z

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!

Answer 51 · 2017-11-23T11:04:25.000Z

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

Answer 52 · 2018-01-11T22:33:11.000Z

Hello @RomanGotsiy,

Any update on the move to react?

Answer 53 · 2018-01-11T23:37:21.000Z

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

Answer 54 · 2018-06-01T14:41:51.000Z

I think this can be closed already 😃

Answer 55 · 2019-05-10T19:13:28.000Z

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

Answer 56 · 2019-05-10T21:59:13.000Z

@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