search

ruby-grape / grape-swagger

Add OAPI/swagger v2.0 compliant documentation to your grape API
MIT License
1.09k stars 471 forks source link

Best way to host the swagger-ui in grape #109

Open btrepp opened 10 years ago

btrepp commented 10 years ago

Is there a minimal example for using swagger+grape+adding a route to show a UI?.

It would be great to host the UI along with the grape-swagger part, so I can just point users to a url and have the documentation all there.

quetzaluz commented 10 years ago

This gem adds the UI to your rails pipeline, pretty easy to use if you're familiar with haml: https://github.com/kendrikat/grape-swagger-ui

dblock commented 10 years ago

Would be nice to add documentation to the README of how to do this, @btrepp want to volunteer?

dspaeth-faber commented 10 years ago

grape-swagger-ui is more outdated https://github.com/d4be4st/swagger-ui_rails But even swagger-ui_rails is not up to date.

I think a documentation how to download all needed scripts from swagger ui and build a simple index page would be more helpful.

krisalyssa commented 10 years ago

https://github.com/wordnik/rails-petstore is reasonably up to date. I don't know if it qualifies as "minimal".

dspaeth-faber commented 10 years ago

@CraigCottingham this app does not include the needed js- and css-scripts for swagger-ui. The needed scripts you can find here. But the question is how to get this js-scripts into you'r own rails app and serve the ui page on you'r own.

btrepp commented 10 years ago

Most examples seem to have rails involvement.

I was actually using grape standalone. Thus far I don't have a elegant solution for this, I did have cross-origin support enabled so I could use web based swagger hosts, but it would be great if I could just mount a engine (possibly via ruby gem? :)) in grape that has the swagger-ui cranking.

It's easier to sell other devs on why ruby/etc is cool if I can give them a url to play with the test server.

krisalyssa commented 10 years ago

@dspaeth-faber Blerg. You're right. The embarrassing thing is, I did the work to rails-petstore to bring it up to date. In the intervening time, I apparently forgot which piece of the puzzle it provides.

+1 for better documentation. IIRC all we had to do in our app that includes swagger-ui was link to a couple of JS files and include a snippet of JS in our view to load it. (At the moment, I don't know how much of what we're doing is strictly necessary and how much is embellishment.)

taybin commented 10 years ago

I gave up on any gems providing this and just put petstore (plus a couple modifications) in my public/assets directory, removing it from the pipeline entirely. As far as I can tell, that's the easiest, short term way. Rails-Assets has a couple swagger-ui components, but I wasn't ready to bring in a new piece of infrastructure on top of everything else.

Fryie commented 9 years ago

I just mounted a mini-sinatra app on an /apidoc route in my config.ru and had it handle the whole swagger UI. I did this, so I could be somewhat more flexible than if I had thrown it all into my public folder (for example I could have the documentation only in staging, but not in production, etc.). Anyway, this still means that I have to download and copy the files from the swagger-ui repo manually, change the asset paths, etc. It would be nice if there was some sort of straightforward integration.

Edit: A further benefit from having a sinatra app is that I can e.g. serve documentation for different api versions later by using a query parameter.