Migrate ReDoc to React - Githubissues

RomanHotsiy commented 7 years ago

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 commented 7 years ago

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

avkonst commented 7 years ago

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 commented 7 years ago

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

RomanHotsiy commented 7 years ago

@avkonst yes, react is pretty good with typescript!

brendo commented 7 years ago

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 commented 7 years ago

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

jsmartfo commented 7 years ago

👍 yes from me!!

j26nz commented 7 years ago

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

KtorZ commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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

RomanHotsiy commented 7 years ago

Hey @j26nz,

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

sudsk commented 7 years ago

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

RomanHotsiy commented 7 years ago

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

RomanHotsiy commented 7 years ago

@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 commented 7 years ago

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 🎥):

[x] left menu (including headings from markdown)
[x] navigation + hash navigation working
[x] middle panel (almost) ready (schema component, responses)
[x] 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 commented 7 years ago

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

philsturgeon commented 7 years ago

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

LeFnord commented 7 years ago

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

sudsk commented 7 years ago

@RomanGotsiy - any news about alpha release? Thanks!

RomanHotsiy commented 7 years ago

@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

ScheerMT commented 7 years ago

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!

shenghu commented 7 years ago

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

sudsk commented 7 years ago

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

MikeRalphson commented 7 years ago

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

RomanHotsiy commented 7 years ago

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

RomanHotsiy commented 7 years ago

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!

MikeRalphson commented 7 years ago

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

j26nz commented 7 years ago

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

jsmartfo commented 7 years ago

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

mikunn commented 7 years ago

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 !

RomanHotsiy commented 7 years ago

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

mikunn commented 7 years ago

@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 commented 7 years ago

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

zufrizalyordan commented 7 years ago

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?

RomanHotsiy commented 7 years ago

@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 commented 7 years ago

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

RomanHotsiy commented 7 years ago

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 commented 6 years ago

@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 commented 6 years ago

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

RomanHotsiy commented 6 years ago

@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 commented 6 years ago

@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 commented 6 years ago

@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 commented 6 years ago

@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 commented 6 years ago

@RomanGotsiy - Yes it works! Thanks!

alexjomin commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

@RomanGotsiy That's fine now ! thank you

shreyas-agnihotri commented 6 years ago

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

RomanHotsiy commented 6 years ago

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!

Redocly / redoc

Migrate ReDoc to React #327

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

Todo