Everything bagel: My experiences with OpenAPI
Over the years, I’ve worked with a bunch of different toolsets and workflows for writing technical documentation. So far, my workflows with OpenAPI have felt the most rewarding in smaller writing teams.
In this post, I discuss:
- OpenAPI advantages that I’ve experienced,
- My current process and publishing workflows (also, limitations), and
- Any related resources I’m working with.
The environment shifts I’ve experienced in 10 years
I’ve been writing technical documentation for 10+ years. In the last 5 years, my writing focus has tuned towards API documentation and developer education. This focus reflects the business needs of startups and mid-sized companies looking to share API services with customers.
With evolving tech stacks and improved resources, engineering teams building API services have generally become leaner. This tracks from a writing team size standpoint as well. In my previous role, I was one of four technical writers. In my current role, I am the only technical writer.
In this time, another shift I’ve experienced has been with documentation toolsets and related workflows.
Toolsets have felt tedious in the past
In 2010, I was part of a team that relied on HTML, CSS, and version control for building documentation. Our team had a lot of control over document design and publishing. But we felt the pain of maintaining style with each new topic we documented.
PDF and even physically printed output was popular at the time. With MS-Word, I remember when our systems would fail while generating PDF output for 500+ pages. Unfortunately, there was no other way to test our work!
When I starting writing in larger teams for enterprise products, I was introduced to DITA — an XML-based model consumed by large CMS platforms. It felt wild to be able to take advantage of powerful features like content reuse, templating topic types (task, concept, reference, etc.), and producing HTML & PDF output at one click.
With leaner engineering teams in the recent years, I’ve been in writing teams of two, four, and one. This environment has demanded the use of much faster documentation workflows and of toolsets with lower maintenance.
My current workflows with OpenAPI stand out for me as a great method for delivering modern documentation experiences at speed.
Workflows with OpenAPI for the win
OpenAPI is an open specification for defining and describing APIs. From a documentation standpoint, fill in information for the required OpenAPI objects and it automatically maps to different sections in API documentation (Sample spec). A text editor and publishing tool is all that is required to begin.
When I first learned about OpenAPI, I was amazed to see an implementation where API documentation was being auto-generated right out of engineering code.
Up until that point as a writer, most of my expertise required learning and working with large and more formal toolsets. Yes all those toolsets are still relevant and yes the toolsets are still very powerful. But in very small teams, I’ve greatly benefited from some key advantages with OpenAPI.
- Lighter toolsets to work with: The OpenAPI spec lives in the JSON or YAML format and feels very lightweight to work with. The order of information in the spec feels procedural and easy to follow. Any free online editor can validate any data in JSON or YAML. With a text editor, Git for version control, and a publishing tool, my workflow is complete. ✅
- Faster publishing workflows: When openapi-generator is integrated with an engineering project, documentation can live in code. This process builds faster workflows where documentation can be auto-generated when a product feature is shipped. I am getting close to this level of parity. ✅
- My work generates output & is used as input: Early in my current role, auto-generating documentation wasn’t an option. My first project was to write the OpenAPI spec for the existing 250+ API endpoints. The spec is published on developer.bill.com (more on my workflows in the next section). Since then, there is a dedicated team building a much more powerful and friendlier API customer experience. The team consumes my handwritten OpenAPI spec as a baseline for generating SDKs and for testing with the current API design (internal documentation). ✅
- More modern documentation experiences: Since 2017, I’ve seen both open-source templates and more well-crafted solutions for publishing OpenAPI documentation. What’s more — the default output is cleaner (no more CSS tampering required) and even interactive! Customers can now test with sample code in the documentation! Readme.com has been my choice for publishing documentation at two different organizations now. ✅
My workflows with OpenAPI
In my current role, I own and maintain API documentation on developer.bill.com. Remember that I manually wrote the OpenAPI spec for the existing API. I started with repurposing the sample pet store YAML for a small subset of endpoints. With repetition, understanding the OpenAPI rules felt easier. However, human error crept in with typing in a text editor and I needed a faster way to identify and fix errors.
I switched to stoplight.io as my OpenAPI text editor. Live linting feels like the biggest advantage of using this product. I mistype an object and stoplight.io throws an error immediately, tells me where the error is, and what the fix is based on OpenAPI rules. In addition, stoplight provides a good live preview of the output. Swagger Editor is another option to consider, but I find it easier to work with the modern stoplight.io experience.
While stoplight.io also provides documentation publishing and hosting, I prefer to work with Readme.com for those needs. The default API customer experience with Readme.com publishing feels more refined. As the only writer, going live with little to no CSS customization is critical for me.
The final piece in my workflow was to maintain a GitLab repository for version control over each addition or update. After publishing documentation for all 250+ endpoints, this repository has been my only source for any future updates. The repository can also be configured with the Readme.com CLI to automatically publish each update I make in the spec.
Since 2022, we have a dedicated engineering team working diligently on upgrading the current API customer experience. In this project, each time the team commits code for adding or updating a feature, OpenAPI output is auto-generated with openapi-generator. In addition, the project repository automatically publishes the output with the Readme.com CLI. While the project is internal, the output is still interactive and usable. My process for adding or updating documentation is different, but it continues to map to elements in published API documentation.
In this example:
- I use the @Operation annotation to document the OpenAPI summary and description objects.
- I use the @Schema annotation to document parameter details, such as data type or example use.
Limitations that I’ve come across
Five years feels like a lot of time for testing and identifying what works well in my workflows and for also finding workarounds (where possible) for limitations. The more important limitations I’ve come across are with the API documentation publishing tools for OpenAPI. In their current iterations, while most of these tools work well for smaller teams, DITA-based CMS platforms win at scale.
For example, when I write a new topic in the Readme.com Guides section, it would be great to be able to easily reuse content from another topic. Or it would be great to build custom templates for topic types (task, concept, reference, etc). Today, with a smaller set of guide topics, these requirements do not feel very painful. But at scale, DITA-based platforms (like Oxygen) win with such features baked in.
When does working with OpenAPI make sense?
I find stripe.com/docs to be the gold standard in technical documentation. The published output feels exhaustive, clean, and interactive! The website is a full-fledged product at Stripe. Product maturity feels so far ahead that Stripe’s authoring framework — Markdoc — has been made open-source.
The point I’m making is that at scale, Stripe keeps pushing boundaries with documentation. For much smaller teams looking to build documentation quickly, the OpenAPI workflows I’ve worked with are a good option. Despite known limitations, you can also benefit from publishing tools like the redoc open-source template (free), stoplight.io, or Readme.com. I’m sure there are more options that I haven’t considered.
For now, I leave you with Tom Johnson’s guide on idratherbewriting.com as great resource with step-by-step instructions for getting started with OpenAPI-based documentation.
