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
Edited by James Lopez