API documentation for KnowledgeOwl
My single largest project in 2021 has been overhauling KnowledgeOwl's API documentation. KnowledgeOwl is a knowledge base SaaS company. The API docs had not been touched in years, and were incomplete (most of the endpoints were not documented at all, and the ones that were didn't have a complete parameter list). The project involved everything from researching tooling, to creating the OpenAPI spec, to overhauling existing docs and writing new tutorials.
The project is ongoing, but now that phases 1 and 2 are complete, it feels ready to share.
This project was hugely satisfying to work on. It delivered value in multiple ways:
- Better documentation for KnowledgeOwl's users: for the first time, there is a comprehensive endpoint reference for API users! There are also introductory materials, and guidance for users new to APIs.
- Better documentation for KnowledgeOwl staff: The full API reference assists support, pro services, and new developers.
- An audit of the API: in the process of creating the spec file, I logged any quirks I found. Some of these have already led to bug fixes.
- Support for REST API documentation in KnowledgeOwl: using Redocly's standalone open source tool, we were able to autogenerate documentation from an OpenAPI spec file and display it within KnowledgeOwl, without any developer effort. We can now offer this to KnowledgeOwl's users
- Groundwork for future projects: this is a docs project, but, crucially, it really started with an OpenAPI spec file. This lays the groundwork for future projects such as test automation.
The project comprises several distinct phases:
- Research, including tooling decisions
- Endpoint reference, supporting material, support for users creating their own REST API docs
- Cookbook and Postman collection
- Leveraging automated API testing, and using the API to semi-automate other QA tasks
Phase 1: Research
Two factors triggered this project: awareness that KnowledgeOwl's API docs needed work, and a desire to support API documentation in KnowledgeOwl.
I proposed using Redocly's free open source offering, Redoc. It allows users to generate documentation from their OpenAPI spec, without the need for any build process or additional dependencies. All we had to do was add the
<redoc> custom element, and pull in the Redoc script file. This approach has several benefits:
- Simple to implement: no need for a user to install anything or do any build process.
- No need for developer resources: it allows us to offer REST API docs support to our users, without our developers having to build new functionality.
There are a couple of drawbacks:
- Loading screen: for large spec files, you end up with a loading screen, as the page is generated on load.
- Customization: although it should be possible to do some limited style customization through settings on the
<redoc>custom element, this seems a little hit and miss. We ended up digging through the CSS and overriding where necessary. This may not be the most elegant solution - though, again, it is accessible to users with limited programming experience.
Despite the drawbacks, the ability to quickly set up good-looking endpoint reference docs from a spec file, without requiring users to have much technical knowledge, meant this approach is great for KnowledgeOwl.
Phase 2: Endpoint reference, other docs, support for users creating their own REST API docs
The deliverables in this phase were:
- OpenAPI spec file. I wrote this in JSON format, in Postman.
- Introductory material. This was largely existing material, edited and refactored to bring it in line with the current knowledge base style, and supplemented with additional info at points.
- A brand new endpoint reference, aimed at developers, using Redoc and the spec file.
- A new tutorial on working with APIs, aimed at users with little or no API knowledge.
- A guide describing how to create REST API docs in KnowledgeOwl, so KnowledgeOwl's users can create their own endpoint reference.
- Internal-only material: some endpoints are for internal use only. I produced a separate spec file for this, and shared it using Redoc in the company internal knowledge base. I also created guidance on working with the new docs setup.
- A blog post to announce the new docs.
Phase 3: Cookbook and Postman collection
Phase 4: Beyond the docs
Testing and QA: we're currently exploring the options here.