Update schema section of README

[patcon]

Slack context: https://archivers.slack.com/archives/C47DJK8H0/p1506368749000003

@Mr0grog said:

The README there is a little confusing and a lot out of date when you get to the schema stuff

Would the following be a good solution for moving that information somewhere less likely to decay?

To Do

• Flesh out swagger.yml API spec to include description on model properties, borrowing helpful text from the removed schema section of README.
• Link to db/schema.rb in web-monitoring-db
• Link to our Swagger UI for the model section. (For sample of how it's rendered, see the "status" prop on the Order model in the demo swagger api docs)
• Remove all content from Schema section
• enable deep-linking in ui ( See: https://github.com/swagger-api/swagger-ui/blob/master/docs/deep-linking.md)

Related: swagger-api/swagger-ui#1369 (comment)

[Mr0grog]

Flesh out swagger.yml API spec to include description…

Also all our existing swagger issues.

Link to db/schema.rb in web-monitoring-db

I am not particularly keen on this idea. That file is very Rails-specific and very much an implementation detail that does not necessarily reflect what you get out of the API.

I guess I should have been more clear in that the “a little confusing” was about the whole Readme, not just the schema section. I feel like I’ve had to fairly consistently re-explain it to a lot of people, so I don’t think it’s doing it’s job of giving an introduction and overview as well as it should.

That said, the above suggestions are good ones for doing away with the schema section and pointing to the resource we are doing a less bad job keeping accurate and up-to-date. That at least solves part of the problem.

[Mr0grog]

This is addressed in #105, I think. (Or hope?)

[lightandluck]

Yes, everything is addressed except for the task about enabling deep-linking (working link: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/deep-linking.md)

Not sure use for this/why?

[Mr0grog]

Oh, I had totally missed that one (maybe because it says UI instead of DB). I’m guessing that was so parts of the schema section (now gone) could link directly to the correct part of the docs. Still a good idea to do anyway, so I just added edgi-govdata-archiving/web-monitoring-db#396.

[Mr0grog]

Closing this since all the sub-items are done.