How I built scalable API documentation system that solved real business challenges?

Docs as Systems, not files. Here’s how I solved real business problems.

[!NOTE] Writers aren’t just writing anymore, we are building systems that solve usecases.

You probably would have heard this sentence(probably from me on LinkedIn or elsewhere). But words without action makes Steve a dull boy.

Here’s a practical example of our business problem and me as writer solved it. This is going to be a series, so stay tuned on full walkthrough in the coming days.

Since I joined my company, managing API documentation for multiple clients with diverse requirements has been a significant challenge. Each client needs a tailored subset of our APIs, and maintaining these documents in Google Docs led to inefficiencies, inconsistencies, and errors due to repetitive manual updates. Here’s how I tackled this issue and developed a scalable solution.

The Problem: Inefficient and Error-Prone Documentation

Our API ecosystem includes a master API document containing 50–100+ APIs, with each client requiring a specific subset:

• Client 1: Needs 20 APIs
• Client 2: Needs 10 APIs
• Client 3: Needs a different combination, and so on…

Initially, I updated the master API document and manually copied changes to each client’s respective document. As our product scaled, this approach became unsustainable, resulting in:

• Inconsistencies: Discrepancies across client documents
• Incomplete Docs: Missing updates in some documents
• Time-Intensive Updates: Repeatedly copy-pasting changes

The growing complexity demanded a better solution.

The Journey: Discovering OpenAPI and Redocly CLI

While analyzing the specifications(from where we build our solution) for API documentation, I came across the OpenAPI standard. Although it provided a structured framework, it didn’t fully address the challenge of managing client-specific subsets. However, it sparked further research.

I explored the partner(from where we build our solution) repository, diving into its structure by examining over 1,000 folders and dissecting the package.json file. This was before the era of accessible AI tools(I only knew ChatGPT), so the process was manual and time-consuming. While their solution offered reusable API definitions based on use cases, implementing it required complex coding, which felt overwhelming.

Then, I discovered Redocly CLI—a game-changing tool that simplified the process.

With Redocly CLI, using code, you could automate the wholething. But people want quick solution, so I built API Sculptor.

The Solution: Redocly CLI and API Sculptor

Redocly CLI provided the functionality to split, bundle, and lint APIs, enabling a streamlined and scalable documentation process. I built a program called API Sculptor using Redocly CLI to address our challenges. Here’s how it works:

Scenario 1: Standard API Subsets

• Input: A master file containing 100+ APIs
• Client Needs:
  • Client 1: 20 APIs
  • Client 2: 10 APIs
  • Client 3: Custom subset

Using API Sculptor:

1. Load the master API file into the program’s interface.
2. Select the specific APIs required for a client’s use case.
3. Generate a tailored OpenAPI specification for that client.
4. Convert the specification into an HTML file, which can be:
   • Embedded in a documentation portal
   • Shared directly with the client as a user-friendly UI

This eliminated the need to maintain separate Google Docs for each client, ensuring consistency and saving time.

Scenario 2: Custom API Specifications

Some clients require not only a subset of APIs but also customized parameters:

• Client 1: 20 APIs with additional parameters
• Client 2: 10 APIs with the same parameters
• Client 3: 5 APIs with certain parameters removed

With Redocly CLI’s decorators, I could customize API specifications without modifying the master file. Decorators allow dynamic adjustments to the API specs, enabling:

• Adding, modifying, or removing parameters
• Creating use-case-specific documentation
• Maintaining the integrity of the master API document

This approach ensures flexibility while keeping the core documentation intact.

The Impact

By leveraging Redocly CLI and API Sculptor, we achieved:

• Consistency: A single source of truth with the master API file
• Scalability: Easily generate tailored documentation for any client
• Efficiency: Reduced manual updates and errors
• Flexibility: Customizable specs for unique client needs
• Professional Output: Clean, HTML-based documentation for seamless integration or sharing

What’s Next?

This is just the beginning. In the next part of this series, I’ll dive deeper into:

• Walkthrough of API Sculptor
• Implementation of decorators
• One command and all the specs are generated(Yes, full automation).

Stay tuned for more insights on revolutionizing API documentation!

---