What design choices make it different from rswag (swagger_rails)?
knarewski opened this issue · 2 comments
I was researching the options for automated documentation of my Rails project, and encountered this gem. It mentions being heavily influenced by swagger_rails, but does not say why it was created in the first place and what are the benefits of choosing it over swagger_rails. The DSL and capabilities look quite similar. Is it worth adding a sentence or two about that in the readme to help people choose?
The interface is very similar but at that point swagger_rails' code structure was very hard to work with and the maintainer and I differed on how to address it so I decided to create my own gem. I'm not actively using any more so the other gem might be a better option at this point.
Thank you for the quick response! I tracked down your original post in rswag, so I can as well quote the differences below just in case someone else has the same question.
Please note that the quote below is 4 years old and things might have changed since. That's also why it may be better to keep README.md intact.
things i'd want to try doing differently:
- being able to capture the output and incorporate that in the examples so they're more living docs is important for my use case
- i'll take the hackier option to overload description method so the DSL matches the swagger spec rather than changing names
- rake task should be running specs and reporting error during docs generation
- not worry about serving of swagger-ui and JSON
- much more granular testing and testing against against multiple versions of rails