Use a documentation generator for the API

That has the following advantages:

• Automated, minimum maintenance and work
• We won't miss fields on endpoints (this is the case right now)
• Improve consistency - the way we document API endpoints differ a lot
• Being able to manage an API changelog in a better way

We could use tools like https://github.com/technekes/grape-markdown, https://github.com/ruby-grape/grape-swagger or write our own.

Originally suggested here: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655#note_34404596

Related: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2397

/cc @godfat