Improving the Developer Experience with Better API Documentation

As enterprises increasingly turn to composable software solutions, developers need to understand how to connect them using RESTful APIs. Great developer experiences require great documentation. Typically, this starts with a schema, and OpenAPI (formerly Swagger) is one of the most popular for describing RESTful APIs. It can be displayed in SwaggerUI, imported into a CCMS (Component Content Management System) like Paligo, used to generate a static HTML site with tools like ReDocly and Slate, or managed in a dedicated API platform like Stoplight.

An API schema tells a developer what the inputs and outputs are for any given endpoint. But, it lacks the context of why they would want to use the endpoint and the prerequisites needed to properly implement the endpoint. For example, an eCommerce website may have a method for adding an item to a basket. However, before that endpoint can be called, there must be an organizational structure in place, perhaps a storefront, inventory of items, and a customer account. Workflows and illustrations can provide this context and help to ensure that the developers are using the endpoint quickly and efficiently.

Content included in OpenAPI is limited to plain text, in some cases, and Markdown with HTML in others. If you want to include images such as workflow diagrams, there is no way to include these directly in an OpenAPI schema, and they will need to be hosted somewhere. If you do manage to add all the additional information such as context, prerequisites and images to the schema, you lose the benefit of having a lean reference document. Developers are forced to navigate through all that extra information when all they’re looking for is the list of inputs and outputs. There is a better way.

You can link your API documentation to a companion site that mirrors the structure of your API schema, and is not limited by restrictions of the schema format. It can include workflows, diagrams, and any additional information that developers need to make effective use of your APIs. The key to linking the companion doc site to the API docs is to use context-sensitive help (CSH) links. These are dynamic links to content in your doc site that can be embedded directly in your OpenAPI schema.

In Paligo you would add a snippet of HTML in the description on an API endpoint. For example:

<button onclick="window.open('../help/en-us/index-en-us.html?contextId=methodname)">More info</button>

This will create a button labeled “More info” in the API docs. When an API doc reader clicks the button, it will open a new browser window or tab (depending on how the user has configured their browser), and display the pertinent information from the companion doc site. If you use the method name as the unique identifier for the CSH, then the person who is editing the schema will immediately know which URL to use. This will be the root of the documentation site with the parameter “contextId”. When the schema edits are complete, the person who made the edits can simply let the writer who is working on the companion site know the name of the new method. They can then easily insert the CSH reference in the docs and publish at will. In the Paligo CCMS, CSH references are added by selecting a topic or section, and adding the “xinfo:appid” attribute with the “contextId” as the value.

You can add as many CSH links as you like. They don’t have to be buttons. And you can include links to your main user docs site as well as your developer companion doc site. The advantage of using CSH links is that they will always point to the correct location in your technical documentation, even if you choose to restructure it later on. The one caveat is that you must make sure that you don’t delete the content in your documentation to which you point your links.

In conclusion, building a companion doc site for your OpenAPI docs in the Paligo CCMS is a crucial step in enhancing the developer experience and ensuring the seamless integration of composable software solutions. RESTful APIs are the backbone of modern software development, and clear, well-structured documentation is the key to their successful implementation. By following the steps and best practices outlined in this post, you’ll be well-equipped to provide developers with the resources they need to make the most of your APIs and contribute to the success of your enterprise. If you would like to read more about the Paligo API, be sure to check out our article “What is the Paligo API and how can you benefit from it?”