IBM Developer Blog

Follow the latest happenings with IBM Developer and stay in the know.

Generate the OpenAPI spec from comments inline with your code


Whether you’re building an application or website, great documentation is crucial to the success of your service. Developers need instructions on how to use your API and they need a way to try it out. Good documentation handles both.

The OpenAPI Specification is an open standard for defining and documenting your API. The OpenAPI Specification enables the generation of great documentation, but creating an OpenAPI spec takes a lot of time and effort to create and keep up-to-date. Often, the OpenAPI spec ends up a large, forgotten, thousandl-ine file.

To help make it as easy as possible to document an API, today we are launching the OpenAPI Comment Parser. The goal of OpenAPI Comment Parser is to give developers a way to generate this OpenAPI spec from comments 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.

This approach brings the OpenAPI spec to the code. It gets broken up into smaller, more manageable pieces. It lives next to the code that it’s describing. This enables developers to easily update the relevant spec when code changes and don’t have to go searching in the giant spec file. We are also introducing a new spec format that is tailor-made for being written in comments. On average, this new format has been shown to reduce the amount of spec needed to be written by 50 percent.

The library is built for Node.js, but the CLI can work with any language that uses this style of comments:

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

We plan on expanding to most popular languages.

See the OpenAPI Comment Parser in action

In the following video, I walk you through a sample scenario that shows how to use the OpenAPI Comment Parser to create documentation for a Node.js API.

How can this make a developer’s life easier?

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.

Try it today

We built this tool to solve some of the problems we face everyday developing services at IBM. Now, developers can try out the new tool on GitHub.