Categories: Latest News Releases

Document APIs with open source OpenAPI Comment Parser

By Nicholas Bourdakos, IBM Developer Advocate

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 Specificationis 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:

/**
* comment
*/

We plan on expanding to most popular languages.

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.

Tags: ibmOpenAPI

Recent Posts

DevOps Deeper Dive: IPO Frenzy Heralds Consolidation

A spate of initial public offering (IPOs) has resulted in billions of investment dollars being poured into JFrog, Snowflake and…

2 days ago

Catchpoint Acquires Webpagetest.org Service

Catchpoint this week announced it has acquired Webpagetest.org as part of an effort to expand use of the open source…

2 days ago

Report: Cloud Expertise Now Superior to University Degree

According to a report by online learning platform A Cloud Guru, 90% of IT leaders expect to expand their cloud…

3 days ago

Harmonizing Real-Time on Edge Platforms

Edge computing platforms sit at the boundary between the real-time world and the digital enterprise. Uninterrupted, uncorrupted data from the…

3 days ago

ServiceNow Extends Reach Into DevOps Ecosystem

ServiceNow this week, as part of a massive Paris update to its core software-as-a-service (SaaS) platform for managing IT operations,…

3 days ago