Pros and cons between Swagger UI, Redoc, RapiDoc

[baboonmaj]

Thank you for providing us with this great library.
This one truly deserves to be at the top of the stack compared to Swagger UI and Redoc.

However this is just my opinion from the limited research I did. Our's is a big organization and deals with multiple micro-service architecture.
When we compared RapiDoc, Swagger UI and Redoc. RapiDoc became an obvious choice based on the feature-sets, theming-support, user-interface and its API layer that feels very natural to program with.

Yet I am surprised why does it have so less adaptation rate. It has very less github-stars, npm-downloads and dont even get mentioned in any of the blogs ?

If you can put up a comparison set somewhere then I think it will help others to pick up the right tool for their work. I am specially looking for where RapiDoc might not fare that well compared to Swagger and Redoc

[Jeegen]

@baboonmaj

Hello,
how to use RapiDoc Can You Provide brief details.

[baboonmaj]

@Jeegen you may checkout their examples provided at https://rapidocweb.com/examples

[dcarr178]

I compared these components a few months ago and am happy to share my research here. In the end I chose Rapidoc in part because it is awesome and in part because I thought I could fix the parts I didn't like and submit my work back to the community.

Rapidoc

• No enhanced markdown (stoplight-flavored markdown with alerts, tab panels, etc). Resolution: I added tab panels feature and it was accepted.
• No support for x-code-samples. Resolution: I added feature and it was accepted.
• Curl code is only shown after you click try button not before. (Fix remains TODO)
• Copy to clipboard button is shown in some boxes but not others. For example, no way to copy curl to clipboard. (Fix remains TODO)

Swagger UI

• Ugly styling (show stopper)
• Really ugly schema/models
• You have to enter "Bearer" before auth token
• No support for x-code-samples
• Curl code is only shown after you click try button not before.

Redoc

• No try-me functionality (show stopper)

[mrin9]

thanks @dcarr178 for the points and your contributions

We do conduct a lot of surveys/feedback from a very large set of users with our sponsoring organizations, but I am not allowed to share my sponsors name or their customer surveys in the open-source section

I will leave this issue open for a while, for our open-source community to provide their feedback

[elipinska]

During my search for a quality OpenAPI definition renderer, I’ve given both Redoc and RapiDoc a spin -- here are the results of my comparison (spoiler alert: RapiDoc was the winner for me):

RapiDoc

Advantages

• Has an excellent API playground with a full authentication flow
• Very fast response time to issues
• Very easy to customise using a wealth of available theme options
• Brilliantly thought-through UI which makes interacting with the docs a pleasure
• Can be embedded in a HTML document
• Gives an option to embed custom HTML within the RapiDoc theme (not something I’ve seen in any other Open API renderer!)
• The team are considering introducing an option for server-side rendering

Disadvantages

• The search functionality is not as good as ReDoc’s (works more like a filter for section headings) which doesn’t work well with larger specs -- I found that if you have a lot of headings, the search results are not always visible unless you scroll through the panel. That said, since all docs are on a single page, it's easy enough to use the browser's search feature to find what you need. RapiDoc explain their stance on this here.
• Automatic XML representation leaves room for improvement but it looks like it's a new feature and developers are still working on it

Redoc

Advantages

• Can be customised by using options and overriding values in the default theme
• Great search functionality
• Can be embedded in a HTML document
• Supports some handy OpenAPI specification extensions, and makes it possible to externalise the content of description fields (you can use $ref in description: to include a Markdown file)

Disadvantages

• Development these days seems to be much more focused on the paid project (Redoc.ly)
• No interactive playground in the free version
• Unhelpful error messages when the OpenAPI definition fails to parse
• Not a fan of how lists of request/response attributes are presented
• The three-column layout can feel very crowded on smaller screens, making the contents of the rightmost column difficult to read

[mrin9]

thanks @elipinska for proving us with your detailed research.

[prashantevolvus]

We tried various different OpenAPI documentation rendered both open source and the commercial ones that allowed free trial.
Started with Swagger.

1. Doc layout is not very intutive and not very attractive
2. Setting it up is not tough but not easy either.
3. No support for x-code.
   Though we use editor.swagger.io for building the openapi doc

Then tried DapperDox

1. It has a clean interface
2. But has a baggage of Golang web modules so deployment and maintenance is tad tougher

Then bunch of other options.

Then Redoc

1. Beautiful interface and very user friendly.
2. Once you get used to that 3 column interface you really appreciate the less clutter. But as @elipinska pointed out in a hand held device usability is a challenge.
3. Easy deployment - just include the JS in your html and it all comes up magically
   It had everything going except for a big show stopper - there is no "Try me"
   We moved to redoc.ly (trial version)
   It is redoc + try me + bunch of stuff for a subscription fee.

Just before were deciding on Redocly we chanced upon RapiDoc.
I think RapiDoc has everything that you may ever need. Flexibility, clean and intuitive interface, easy to deploy, very good documentation and examples. It is a clear winner.

I would like to thank the team for this wonderful contribution.

[mrin9]

We have been working hard on RapiDoc to further improve upon our User Experience. We have added many more features since the above feedback we received - I have created RapiDoc's Feature Listing in #428 - This may be useful for people looking for quick analysis while they decide on picking up an OpenAPI renderer for their use case

[technicaltitch]

I wanted to add a very important and often overlooked advantage to RapiDoc, and that is accessibility. I evaluated Swagger, Redoc, Slate and RapiDoc using webaim.org, and RapiDoc raised far fewer warnings than any of the others (Slate came closest). This is a moral imperative, and increasingly mandatory for many clients especially when the payer is governmental. (And often compliance doesn't come along until the end of a project, by which time chaos ensues.)

[francipvb]

Hello all,

What about OpenIDConnect?

Thanks!

[dmytro-samodurov-ag]

Great layout and rendering customization is one of the advantages of RapiDoc. Thank you! It is currently the choice for documenting our api.

Are there plans to move RapiDoc customizations further? e.g. Ability to render Components section and its items selectively in the "read" mode?

[Layap]

Do we have the support of external CSS and JS in case of ReDoc as we have in RapiDoc? Thanks!

[WilliamStam]

ive never liked the look of swagger-ui. its actually 1 of the reasons ive stayed away from api work in general cause they all need to be documented and swagger... yeah.. no... but i didnt have a choice this time round. i ended up doing around ~1000 lines of css to try make swagger ui less of a pain.. but then just gave up. and somehow rapidoc came up (cant recall now how tho but it was by chance), to be honest, this is 1 AMAZING project. just about everything ive thought "hmm that could be nice" is already implemented, and the WAY its implemented... at the dev... i take my hat off. its been a while since ive been truly impressed with something the same way. with the formalities out of the way (the soppy soppy had to be said!):

i think maybe the reason it hasnt gone more widespread has to do with the name. when going through the list of openapi.tools i dont think i would have even clicked on rapidoc unless i went through each individually. the project (in total, everything including the docs) is soooooo good it should be the defacto standard but somehow it isnt, and i dont understand why... no one ive spoken to has even heard of it till now.

swagger-ui is just out. no use even comparing the 2.

things i would like to have in rapidoc:

• more classes on sections or to have more part selectors (for instance having the info, operations, paths each having their own way to be controlled - like now i tried to find a way to remove the "operations" block but couldn't - (no biggy tho) but would be cool adding a bunch more "we give you most of the ways to control YOUR documentation, but if we dont have the option you can add it in yourself" but that would involve a lot more selectors. (ie <3 [Feature Request] a class or way to style the "selected" path option #827 (comment))
• in column on the side mode to maybe have it "fixed" but was SUPER easy to implement my side in any-case cause of how customization the system is, was just slightly strange that it wasnt the standard.
• slightly better docs on the css variables and maybe more use of them (but i confess i didnt look too deeply here. got stuck on the parts part and didnt need to go further)

<3

[KomalYadav10796]

Hello @prassie @mrin9 ,
We're experiencing issues with Redocly.
We are receiving null responses for some of the variables.
We're using the same code and swagger schema everywhere, but it's not working in some places while getting responses from body.
As shown in the screenshots.

Could you please help me with this? Thanks!

[prassie]

For somebody who checks on this thread to know the advantages of RapiDoc, here's an example which demonstrates the various options in RapiDoc:
https://rapidocweb.com/examples/api-demo.html

[sandeep-kr-yadav]

Ask: Is it currently possible to have the following as of today?
Attribute
name: "userIds"
type: array

As of today we need to pass the values in text box.

To improve the user experience, if we could allow users to just skip the [ ] in the request and allow them to just click on add item button and then the values can be filled in, which can then be translated to [ "",""] in CURL command in Try out panel