API documentation for KnowledgeOwl

Published: Last updated:

Screenshot of the KnowledgeOwl endpoint reference

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.

Value

This project was hugely satisfying to work on. It delivered value in multiple ways:

Stages

The project comprises several distinct phases:

  1. Research, including tooling decisions
  2. Endpoint reference, supporting material, support for users creating their own REST API docs
  3. Cookbook and Postman collection
  4. 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:

There are a couple of drawbacks:

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:

Phase 3: Cookbook and Postman collection

Coming soon!

Phase 4: Beyond the docs

Testing and QA: we're currently exploring the options here.