IBM's OpenAPI Comment Parser Brings API Reference and Code Development Together

IBM has introduced OpenAPI Comment Parser. The new offering brings API reference creation and code development into the same environment. The theory is that API references will improve, and stay updated, if developers don’t have to bounce back and forth between their code and the API Reference that tells developers how to use that code.

“When the [API reference] lives inside the code, developers are much more likely to keep it up-to-date as their code changes,” IBM’s Nicholas Bourdakos commented in a blog post announcement. “It gets broken up into smaller, more manageable pieces. It lives next to the code that it’s describing."

More specifically, the Comment Parser enables developers to generate an OpenAPI spec from the parser itself. The OpenAPI Specification is an open standard for defining and documenting an API. Using the parser to create OpenAPI specs, IBM reports that it has been able to reduce the size of API references by 50% on average. Given the typical size of API references, this is significant.

The Library is open source and written in Node.js. However, the CLI will work with any language using the following comment style:

* GET /users/{userId}
* @summary Returns a user by ID.
* @pathParam {int64} userId - The user's ID.
* @response 200 - OK

To learn more, visit the OpenAPI Comment Parser at GitHub.

Be sure to read the next Tools article: Red Hat Introduces OpenShift 4.5