IBM creates open source tool to simplify API documentation


The OpenAPI Comment Parser for Developers aims to make it easier to write and read good API documentation.

Image: IBM

APIs are essential for programming, but they can get complicated. IBM has released a new developer tool that should make writing API documentation a bit easier: The OpenAPI comment analyzer.

“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 comment. blog post about the new developer tool.

Must-read developer content

Open api is a specification that was designed as a language independent 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 a network traffic inspection, “said the API maintainer tool swagger.

The comment analyzer is designed to work around a problem that Bourdakos says is common for developers working with the OpenAPI specification: OpenAPI specifications for recording comments must be built and maintained manually, which means they are often forgotten and become bloated and unnecessary.

SEE: Quick Glossary: ​​DevOps (TechRepublic Premium)

“The goal of OpenAPI Comment Parser is to give developers a way to generate this OpenAPI specification from comments inline with their code,” Bourdakos said.

The OpenAPI specification under the comment parser lives inside the code, broken up into smaller chunks that can be more easily updated because the need to search a giant spec file is eliminated. “On average, this new format has been shown to reduce the amount of specs to be written by 50%,” Bourdakos said.

Bourdakos demonstrates how the OpenAPI comment analyzer works in a video, where he uses Docusaurus with the comments parser to create an API documentation site. The site’s graphical layout extracts OpenAPI specification comments from its code and presents them in an easy-to-see way using markdown.

The Docusaurus interface makes comments easy to view, search, and review, and because they are written in line with the code, thanks to the parser, a developer who needs to make changes to a particular section can simply put updated this comment.

The comment analyzer, Bourdakos said, is designed to make developers’ lives easier by removing unnecessary documentation code. Not only does this save time, but it also makes the code itself more manageable, he said.

SEE: Top 5 Programming Languages ​​For System Administrators To Learn (Free PDF) (TechRepublic)

The generation of documentation by the feedback analyzer can also be used to test the API, so developers can “spend less time waiting for an interface to be built or relying on other tools to test. their API, ”Bourdakos said.

IBM’s OpenAPI comment parser was designed for use with Node.js, but its command line interface will work with any language that uses a similar comment style. IBM will add support for additional “popular languages” in the future.

In the meantime, developers who use Node.js or a language with a similar comment format can now try the OpenAPI comment analyzer.

Also look


Sam D. Gomez