IBM launches OpenAPI, an open source tool to simplify API documentation
APIs are essential to programming, but they can get complicated. IBM has launched a new tool for developers that should make writing API documentation a bit easier: The OpenAPI Comment Parser.
“Developers need instructions on how to use your API and they need a way to try it out. Good documentation handles both,” IBM developer advocate Nicholas Bourdakos said in a blog post about the new developer tool.
OpenAPI is a specification that was built as a language-agnostic interface for RESTful APIs, “which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection,” said API tool maintainer Swagger.
The Comment Parser is designed to work around a problem that Bourdakos said is common for developers working with the OpenAPI specification: OpenAPI specs for recording comments have to be built and maintained manually, which means they often get forgotten and become bloated and useless.
“The goal of OpenAPI Comment Parser is to give developers a way to generate this OpenAPI spec from comments inline with their code,” Bourdakos said.
The OpenAPI spec under the Comment Parser lives inside the code, broken up into smaller pieces that can be more easily updated because the need to go searching through a giant spec file is eliminated. “On average, this new format has been shown to reduce the amount of spec needed to be written by 50%,” Bourdakos said.
Bourdakos gives a demonstration of how the OpenAPI Comment Parser works in a video, where he uses Docusaurus along with the Comment Parser to make an API documentation site. The graphical layout of the site pulls OpenAPI spec comments from his code and lays it out in an easy-to-see fashion using markdown.
The Docusaurus interface makes comments easy to see, search, and review, and because they’re written in-line with the code, thanks to the Parser, a developer who needs to make changes to a particular section can simply update that comment.
The Comment Parser, Bourdakos said, is designed to make developer’s lives easier by eliminating superfluous documentation code. Not only does this save time, but it also makes the code itself more manageable, he said.
Documentation generation by the Comment Parser can also be used to test the API, so developers can spend “less time waiting for a frontend to be built or having to rely on other tools in order to test drive their API,” Bourdakos said.
IBM’s OpenAPI Comment Parser was built for use with Node.js, but its command line interface will work with any language that uses a similar comment style. IBM will be adding support for additional “popular languages” in the future.
In the meantime, Devs that use Node.js or a language with a similar commenting format can now try the OpenAPI Comment Parser.
