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/
Tools for generating HTML pages
There are two nice tools that provide the 3-column page we all know and love:
- https://github.com/Rebilly/ReDoc
- https://github.com/technekes/grape-slate
- 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.
Proof of concept
Visit: https://axil.gitlab.io/swaggerapi/
From https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2397#note_25057321
I created a PoC based on the json export 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.
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.
- The generated 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?