API reference is often crucial, but can only be used when the content is
current, frequently published, and easy to find. Using OpenAPI (Swagger) and Redocly, I can set up an
automatically rebuilding API reference site. After this, engineers can easily maintain the new site,
ensuring that any published reference always matches the API they ship.
Common API reference docs issues
A lot of API teams will already have an OpenAPI Specification. But the following often take place after it is written:
A broken reference site build, causing publishing to fall behind updates.
A broken build makes the reference publishing a manual process, meaning someone must remember to update it.
Swagger UI defaults to a page style that is hard to navigate and doesn't look like the rest of your product or documentation.
All engineers are unfamiliar with the build, meaning they are unwilling to attempt a fix.
The Process
I audit your current spec, identify any issues, and decide on a plan of action.
I take your OpenAPI spec and create an automated build process with Redocly. If you already use Swagger UI, you choose whether to migrate to Redocly or fix the existing build.
I update the theme to make the reference match your product, so it slots into your documentation site easily. This way, developers can move between guides and reference smoothly.
I automate the build through your CI/CD pipeline on GitHub, GitLab or Bitbucket, so every push to the main branch rebuilds and publishes the reference site. We can also set up a preview step or branch at this point, so future changes can be reviewed before they go live.
If necessary, I add supporting documents to help developers get started with your API.
Finally, I hand over the build along with supporting docs, so any developer on your team can maintain it.
Example: rebuilding a broken API reference at GraphAware
At GraphAware, we needed to get the API reference for our Neo4j-based graph platform publishing again, and bring it up to date.
Engineering had maintained a mostly accurate OpenAPI spec, so I had the content I needed. Using Redocly, I updated the site, generating it from the spec, and then made sure it could update through Git, like the Antora documentation. I sent a summary of the build steps to the CTO, who was able to slot this process into the company's existing CI/CD pipeline.
In the end, we had a working reference site that updated from an existing Git repository, which engineering could rely on to update with Git pushes. Since then, I have developed CI/CD publishing pipelines from scratch, so I can now handle the whole process, creating a published site from an OpenAPI spec.
Who owns the spec?
You and your engineers do. I'll keep the OpenAPI spec in your codebase, and won't change how it is written or maintained. My work is just the process: taking the spec and creating a usable site, which publishes automatically, and making sure that process is reliable.
Tools
OpenAPI (Swagger) specifications
Redocly and Swagger UI
Git, with CI/CD on GitHub, GitLab or Bitbucket
Antora or Docusaurus, for the guides around your reference