Open Source API Documentation Tools (And Why They Matter)

Developers first experience your APIs through the documentation. In many ways, an API is only as good as its documentation. Without some idea of what’s available, your consumer whether they’re a trusted partner or an internal collaborator would not be able to build a robust integration. Of course, it’s easier said than done to actually create that documentation. Someone must describe everything that’s possible to do with your API in an organized way.

As we’ll show in this post, there are formats and open source tools that make API documentation more approachable. If your team is building many APIs, a repeatable documentation process will bring consistency to your API program. Now there is no single ‘best API documentation tool’ (though I’m biased towards Stoplight), but here’s some things to keep in mind.

Manually Updating Your Docs Is Cumbersome

Before we skip to the automated solutions, let’s look at what it takes to manually update documentation. You may recognize some of this from your existing workflow. Or, perhaps you’re skipping some of these steps because of the effort to keep it updated. There are many types of API documentation, but here we’ll mainly be focused on API references.

You may have good reasons to manually update documentation right now. You may want complete control over the documentation contents and styling. Certainly, handmade references give you the most power over your documentation. However, in addition to being time-consuming, manual documentation is also error-prone.

Consider the elements of documenting a single endpoint. At a minimum, you need to show:

• The path to the endpoint
• A description of how it’s used
• The valid HTTP methods
• How to send request data with each method
• What HTTP response codes are possible
• The response data with each response code

Now multiply this list across every endpoint. Add in an explanation of authentication and a detailed explanation of any common response and error fields; it can be a lot

But let’s say you now have a fully fleshed-out API reference with everything a developer would ever need to consume your API. Great! You’re just in time for a new version of your API, time to go back through and ensure it’s all updated.

As you can see, this process is at best cumbersome. Your documentation should not become a never-ending push. Unless, of course, that’s a git push that kicks off your continuous documentation process.

API Documentation Generators Ease The Load

You don’t need a complete CI/CD pipeline to take advantage of API reference generators (though that’s not a bad end goal). All that’s required is an API description document, such as one following the OpenAPI Specification. There are a growing number of industry tools that can help you create your OpenAPI definition and convert it into a more human-readable API reference.

For example, consider this snippet of an API endpoint description:

paths:
  '/customers/{customer_id}':
    parameters:
      - schema:
          type: integer
          example: 123456
        name: customer_id
        in: path
        required: true
        description: Unique customer identifier
    get:
      summary: customer
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_id:
                    type: integer
                    example: 123456
                  customer_name:
                    type: string
                    example: Roy Fielding
      operationId: get-customers-customer_id
      description: Retrieve a specific customer by ID

It includes the HTTP method, request data, response object, and more. Anything required in a robust API reference can be described within your OpenAPI. That allows any number of open-source tools to generate documentation like this:

There’s still effort required with each API update, but it’s much less than the entirely manual approach. Imagine in the next version of your API you updated the customer object to include additional fields. That could impact multiple endpoints and HTTP method combinations. You could easily miss some of these in your manual documentation pass. When your models are stored within OpenAPI, you only have to update your definition.

Granted, automated API references are most impactful when you’ve adopted the design-first API workflow. However, you can begin to experience the benefits alongside your current practice.

Automate and Customize with Stoplight Elements

One common issue with API documentation tools, open-source or otherwise, is you’re required to adopt an entire platform. In order to get the advantages of automation, you give up the control you’d have with a manual process. After seeing these problems come up with customers, we released ouropen source documentation generator, Stoplight Elements.

Rather than require you to adopt the entire platform, you can pick and choose web components to customize how your API reference and other documentation is organized. Since each component is powered by OpenAPI, you’ll be able to automatically generate them as your API changes.

For more on best documentation tools and open source tools we love, check out this post.