IBM has released a new open-source API documentation tool to help developers provide better documentation and try out new APIs. The OpenAPI Comment Parser enables developers to document code for OpenAPI specs in a clean and simple way.
The company focuses on the OpenAPI specification because it provides an open standard to define and document APIs. However, the company found that this often takes a lot of time and effort to keep the documentation and API up-to-date. “Often, the OpenAPI spec ends up a large, forgotten, thousand-line file,” Nicholas Bourdakos, an IBM developer advocate, wrote in a post.
The OpenAPI Comment Parser is meant to address this by enabling developers to comment inline with their code. “When the OpenAPI spec lives inside the code, developers are much more likely to keep it up-to-date as their code changes,” Bourdakos wrote.
This will also break code down into smaller and more manageable pieces, Bourdakos explained.
In addition, IBM is releasing a new specification format for comments, which reduces the amount of specification needed by 50%.
Bourdakos added: “The Comment Parser automatically creates better documentation with less code that is more manageable. On top of these improvements, developers writing the API can use the documentation generated from the Comment Parser to test their API. This means less time waiting for a frontend to be built or having to rely on other tools in order to test drive their API.”
