Updated Swagger

[btyy77c]

Context

• Installed Swagger using webpack and removed the html/js/css from the public folder.

Summary of Changes

• Deleted files from the public folder
• Install Swagger using Yarn
• Added Route, Controller, View, and JS to run Swagger

WARNING: Since I updated swagger, the classes changed and the css is no longer valid. I added some basic CSS but the swagger layout is completely different now.

Checklist

• Tested Mobile Responsiveness
• Added Unit Tests
• CI Passes
• Deploys to Heroku on test Correctly (Maintainers will handle)
• Added Documentation (Service and Code when required)

Screenshots

Before

After

[DeeDeeG]

@btyy77c, Thanks for this! I'll test this in just a moment and see if this works on my machine.

[DeeDeeG]

This looks pretty good!

Link to screenshot.

The CSS does need a bit of updating, sure, but it's functional.

Unrelatedly to this pull request, my Docker instance still isn't loading any restroom entries from db/export.csv, so this is hard to test unless you manually submit a new restroom during testing.
Update: see comment below.

I'm not sure if we should allow the POST method at this time, would want feedback from @mi-wood or @tkwidmer. But if we get API submission functionality for free by doing that, we would eventually want to enable it (after making sure we have good spam filtering I suppose.)

All-around, my impression is that it's better to have this as a nodejs dependency than pasted into the repo as html/css/js files. So I'd personally be happy to merge once we're finished reviewing and perhaps polishing the appearance and/or tweaking the configs a bit.

[DeeDeeG]

I have a pull request that makes it easier to test this sort of thing: #508

[tkwidmer]

Overall this looks really great to me. My only concern is adding a POST, although this is something we obviously want to do. I don't want to end up polluting the db with a lot of random requests.

[btyy77c]

Overall this looks really great to me. My only concern is adding a POST, although this is something we obviously want to do. I don't want to end up polluting the db with a lot of random requests.

Can you help me understand where you are seeing the new POST action? No POST action was added from this branch. It's possible it's showing you a POST action already available in production, but I'm not seeing any POSTs when I view the page. Thanks!

[DeeDeeG]

My apologies for the mixup, I can see now that POST is not functionally new in this pull request.

Can you help me understand where you are seeing the new POST action?

When you submit an API request through the docs page, the new interface exposes what methods are allowed:

(The old interface didn't show that info.)

No POST action was added from this branch. It's possible it's showing you a POST action already available in production [. . .] .

Yep. That's what happened. (Whoops.)

Conclusion: If we want to discuss or address the fact we appear to (already, regardless of this pull request) allow POST through the API, I think we can move that discussion out of this pull request.

I'd also like to do some work on the CSS, and maybe even consider the older version of the package; This isn't powering the underlying API backend, just the documentation interface (front end). If the older package was more user-friendly, we may as well go with that, barring any security patches that may have been added. Will look into this when I get time. (I'm sort of taking the day off, but wanted to respond to this.)

Thanks for pointing that out.

Best,

-DeeDeeG

[DeeDeeG]

For reference, swagger-ui and swagger-ui-dist with no custom CSS both look exactly like this:

[DeeDeeG]

There is actually a stylesheet included in the node package swagger-ui.

See: https://github.com/swagger-api/swagger-ui/blob/master/dist/swagger-ui.css

I'm really unfamiliar with JavaScript programming, and with the Rails asset pipeline, (and with Webpacker...) so it's unclear to me how to use this.

I actually prefer what this Pull Request has so far over that stylesheet, though. So maybe we can update the stylesheet slightly so it looks more like what we have in production. (Or if someone understands better how this all works, we might be able to use the swagger-ui package's 2.x series.)

[DeeDeeG]

2.x branch of swagger-ui can't be used since it does not support recent Grape versions. We are looking to update Grape to at least 1.1 when we get the chance, so I'm thinking this pull request is the right time to do that.

[DeeDeeG]

I think we can/should merge this as-is and do any fixups we need later. It would be nice to have up-to-date Grape and Swagger-UI.

(CSS tweaks or tweaks to the API code could come later if we want. But neither of those is strictly needed, they're just nice-to-haves.)

[DeeDeeG]

Would like to finally merge this soon.

I have a work-in-progress branch that fixes up the CSS foor the API docs page, done so as to mostly match the visual style of the 2.x branch of swagger-ui.

But it would be great to have this merged. Particularly since it upgrades grape.

---

Would want to co-ordinate with mobile app folks on this. Want to make sure this will not change the .json output of the API. We don't want to go breaking the apps!

I already know this would have the exact same formatting as it does now: https://refugerestrooms.org/api/v1/restrooms.json

But this file would change a bunch: https://refugerestrooms.org/api/swagger_doc.json (becomes much longer and more detailed, none of the fields seem to stay the same.)

URLs are stable from before this update to after, so there shouldn't be a need to update request URLs or anything.

(cc @hissingpanda, @Carmen-Git-It @hkellaway )

[DeeDeeG]

Merging so we can test the mobile apps against the develop branch's (auto-updating) Heroku instance: https://refuge-staging-14.herokuapp.com/

(Once I update this branch (rebase it on top of develop), and assuming that passes CI)

[DeeDeeG]

Thanks, and sorry it took so long!

---

This updates our grape gem (API backend framework) and swagger-ui (API documentation and demonstration UI).

Looks good to me.