Use the OpenAPI specification for the API docs
Formerly known as Swagger, OpenAPI is an initiative to standardize the way an API is documented.
- Useful blog post series that describe the swagger 2.0 behavior http://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/
- How mattermost does this: Specification is written manually in multiple yaml files and then redoc is used to build the site that eventually lives in https://api.mattermost.com/. There are ways to automatically generate a json file out of our grape API, will need to investigate if it is enough.
- We already have an MR that demonstrates this https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2397
- List API endpoints to change in 9.0 https://gitlab.com/gitlab-org/gitlab-ce/issues/20070