WIP: Expose Swagger API

Open Kamil Trzcińśki requested to merge swagger-api into master

This MR adds a Swagger API endpoint with API viewer for easy API access.

Closes gitlab-org/gitlab-ee#2537

Current status


Ship this as-is, every GitLab instance will have a swagger endpoint.

Issues to resolve

  • We still provide a lot more information in our markdown docs than the Grape API descriptions, and there are also relative links pointing to other API docs. Not sure how to do that with Grape.
  • AFAIK, the generated swagger HTML is one page, whereas the current API docs are split in multiple docs. We'd have to redirect whole pages to anchor links. Again, not sure how clean those new URLs will look like. The question is how will we replace https://docs.gitlab.com/ce/api/ and https://docs.gitlab.com/ee/api/ without breaking links?
  • We need to expose 2 versions of the API, v4 and v3, how do we do this?

Tools for generating HTML pages

There are two nice tools that provide the 3-column page we all know and love:

Proof of concept

Comment https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2397#note_25057321

I created a PoC based on the json export that @connorshea gave me and used https://github.com/Rebilly/ReDoc which is what Mattermost is using . The result is https://axil.gitlab.io/swaggerapi/, but it takes ages to load. That was the best interface I could find that would easily convert our openapi json export in readable API docs. A drawback is that is generates non-friendly URLs like https://axil.gitlab.io/swaggerapi/#operation/putV3GroupsId.

Edited by Toon Claes