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