How to Keep API Docs Consistent with Reusable Blocks

Trying to integrate an API, only to find the docs are a mess. We’ve probably all been there. It doesn't matter if it's a two-month-old startup or an established leader in the space. There's always something (s)lacking.

One endpoint uses id, another user_id, and the error formats change depending on who wrote the page. It’s beyond frustrating, time-wasting, and leads to bugs. There's no single tool that can address and account for all the human-induced issues, but there are areas where we can start. Reusable blocks in Voiden can help solve parts of this issue. They’re simple, help save your time and keep your docs consistent across projects, and work offline in Git.

Why Inconsistent Docs Drive Devs Nuts

There are more than a few reasons why API docs go stale quickly. Yet whatever the reasons may be, the effects are the same. Fru-stra-ti-on. On repeat.

Partially, it has to do with the fact that no one deeply cares about API documentation as long as it works. People just take that it works well for granted. When it causes pain, well, that’s a whole other story.

Devs have been venting about this for years, just check it out on X, Reddit, HN, anywhere really. If you haven’t experienced it first hand (I doubt it), here’s what it usually looks like:

There’s no fun in spending hours doing something that should have taken less than a few minutes. It’s as simple as that.

These mismatches (different field names, outdated endpoints, version-specific gaps, etc.) force devs to debug docs instead of code. Reusable blocks, however, let you write common bits once and reuse them everywhere across the project, cutting out most of the causes for inconsistency in the first place.

Reusable Blocks Remove Duplication and Inconsistencies

Modularity becomes important when there are repetitive components across endpoints, and those are usually headers, query params, response objects, error codes, (environment) variables, etc.

Let’s create small, modular chunks of API documentation in .void files for a dummyjson /posts endpoint. As a starting point, here’s the basic endpoint, with query parameters and documented basics:

Now, if we were to add another GET /objects request, we’d notice some of this stuff is already repeating.

Let’s quickly define BASE_URL within the .env file and set its value to https://dummyjson.com. To use it, just add the variable key in the double curly braces where you’re planning to use it.

Btw, make sure you’re using the correct environment for testing. Check below to see how to select it.

Next, let’s create and import a reusable block named query.void that holds query parameters.

To create a query parameter table, type /query and hit Enter.

Populate the key-value pairs and add some documentation, if need be.

To reuse it, go to where you need the query params, type @, select Blocks, then pick the query params block, and hit Enter.

If you ever need to edit it, just edit the reusable block, and the changes automatically apply wherever the block is imported.

Oh, and if you need a custom query param for an endpoint, alongside the ones used across the board, just add a new query param table to the endpoint you’re testing. The same goes for headers and other reusable fields.

That’s it. The same approach can be used for other reusable types of API request blocks, saving you tons of time on copy-pasting/typing, but also on applying the changes to these fields in the future and editing once instead of N times (N being the number of endpoints using any given field/object), making your API docs much more consistent.

Let’s Look at the Pros

Reusable blocks are like DRY for API documentation. Write an error format once, use it everywhere. If it changes, update one file, push to Git, and all docs stay consistent. It solves the pain of “reverse engineering JSON responses” by giving devs clear, predictable docs.

Stripe’s docs show how it’s done. Endpoints use the same error and auth formats, no matter the service. You can tell they are at least trying to make it uniform across the platform, if not even reuse certain components to keep things tight.

That is the goal: docs that feel like one voice, not a patchwork of team/mood styles.

Try It Out

• Install Voiden: Download the offline app and set up an API repo.

• Document your first API endpoint: Start with a single API spec.

• Collaborate via Git: Use the in-app terminal to commit your changes, open a PR, and let your team review it using your existing Git tools.

Join our GitHub Discussions to share feedback and shape Voiden's future.

Download Voiden and start building APIs the right way.