New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrate ReDoc to React #327

Closed
RomanGotsiy opened this Issue Aug 17, 2017 · 54 comments

Comments

Projects
None yet
@RomanGotsiy
Contributor

RomanGotsiy commented Aug 17, 2017

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

@RomanGotsiy RomanGotsiy changed the title from Migrate view layer to React to Should I migrate ReDoc view layer to React? Aug 17, 2017

@RomanGotsiy RomanGotsiy changed the title from Should I migrate ReDoc view layer to React? to Should I migrate ReDoc view layer to React? 👍 or 👎 Aug 17, 2017

@khorolets

This comment has been minimized.

Contributor

khorolets commented Aug 17, 2017

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

@avkonst

This comment has been minimized.

avkonst commented Aug 17, 2017

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?

@amanganiello90

This comment has been minimized.

amanganiello90 commented Aug 17, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Aug 17, 2017

@avkonst yes, react is pretty good with typescript!

@brendo

This comment has been minimized.

Contributor

brendo commented Aug 18, 2017

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

This comment has been minimized.

Contributor

philsturgeon commented Aug 19, 2017

@jsmartfo

This comment has been minimized.

Contributor

jsmartfo commented Aug 19, 2017

👍 yes from me!!

@j26nz

This comment has been minimized.

j26nz commented Aug 21, 2017

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

@KtorZ

This comment has been minimized.

KtorZ commented Aug 22, 2017

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

This comment has been minimized.

erlend-sh commented Sep 9, 2017

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

@RomanGotsiy RomanGotsiy changed the title from Should I migrate ReDoc view layer to React? 👍 or 👎 to Migrate ReDoc to React Sep 12, 2017

@RomanGotsiy RomanGotsiy added the wip label Sep 14, 2017

@j26nz

This comment has been minimized.

j26nz commented Sep 18, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Sep 19, 2017

Hey @j26nz,

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

@sudsk

This comment has been minimized.

sudsk commented Sep 19, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Sep 19, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Sep 19, 2017

@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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Sep 26, 2017

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

  • oneOf support 🎉
    sep-25-2017 22-16-20

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 👋

@bennyn

This comment has been minimized.

Contributor

bennyn commented Sep 26, 2017

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

@mikunn

This comment has been minimized.

mikunn commented Oct 16, 2017

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

@shenghu

This comment has been minimized.

shenghu commented Oct 17, 2017

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

  1. id='example' is required now.

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

@zufrizalyordan

This comment has been minimized.

zufrizalyordan commented Oct 18, 2017

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?

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Oct 22, 2017

@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

This comment has been minimized.

j26nz commented Nov 1, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Nov 10, 2017

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

This comment has been minimized.

j26nz commented Nov 19, 2017

@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

This comment has been minimized.

SebastianStehle commented Nov 19, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Nov 19, 2017

@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

This comment has been minimized.

sudsk commented Nov 20, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Nov 20, 2017

@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

This comment has been minimized.

sudsk commented Nov 20, 2017

@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

This comment has been minimized.

sudsk commented Nov 20, 2017

@RomanGotsiy - Yes it works! Thanks!

@alexjomin

This comment has been minimized.

alexjomin commented Nov 21, 2017

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

This comment has been minimized.

Contributor

RomanGotsiy commented Nov 21, 2017

@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

This comment has been minimized.

alexjomin commented Nov 21, 2017

@RomanGotsiy That's fine now ! thank you

@shreyas-agnihotri

This comment has been minimized.

shreyas-agnihotri commented Nov 23, 2017

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Nov 23, 2017

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!

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Nov 23, 2017

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: APIs-guru/create-react-app-redoc@da80371

@runes83

This comment has been minimized.

runes83 commented Jan 11, 2018

Hello @RomanGotsiy,

Any update on the move to react?

@wopian

This comment has been minimized.

wopian commented Jan 11, 2018

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

@RomanGotsiy

This comment has been minimized.

Contributor

RomanGotsiy commented Jun 1, 2018

I think this can be closed already 😃

@RomanGotsiy RomanGotsiy closed this Jun 1, 2018

cebe added a commit to cebe/openapi.tools that referenced this issue Oct 2, 2018

Update tools.yml
v3 support on redoc seems to be complete Rebilly/ReDoc#327

@cebe cebe referenced this issue Oct 2, 2018

Closed

Update tools.yml #43

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment