Also add specs and documentation

Edit intro to docs page

Edit docs examples

- Rearrange example requests and responses
- Surround request URLs in quotation marks

Apply suggestion to app/finders/resource_milestone_event_finder.rb

Apply suggestion to doc/api/resource_milestone_events.md