IBM's OpenAPI Comment Parser gives developers a new tool to simplify the process of documenting APIs, so that developers down the line will be able to use them with less effort.
IBM has released a new open source tool called the OpenAPI Comment Parser to help developers streamline the API process when building an application or website.
APIs require good documentation so that developers who want to use them to build services, apps and websites will be able to do so without a lot of effort.
"The OpenAPI Specification is an open standard for defining and documenting your API," said Nicholas Bourdakos, a developer advocate at IBM, in a blog post. "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, thousand-line file."
IBM created the OpenAPI Comment Parser to simplify the process of documenting an API. The tool enables developers to generate the OpenAPI spec from comments inline with their code.
Dylan Schiemann
"When the OpenAPI spec lives inside the code, developers are much more likely to keep it up to date as their code changes," Bourdakos said in his post.
IBM's OpenAPI Comment Parser is a practical tool designed to simplify and speed the update process for code written in Node.js. It pulls comments from a developer's code and generates an OpenAPI document. Rather than creating an OpenAPI document in YAML, developers can write API details in the comments within their code.
OpenAPI was formerly known as Swagger. SmartBear acquired the Swagger technology in 2015 and donated the spec to the OpenAPI Foundation, which changed the name to OpenAPI. However, SmartBear retained the Swagger name and still refers to its tooling as Swagger, such as Swagger UI and Swagger Editor.
IBM's parser is a good idea, and SmartBear has a tool that does something similar for Java, said Stephen Mizell, director of product management at SmartBear.
"It's a very popular approach," Mizell said. "IBM here has made this annotation more general so that you can do it in any language that supports their comment style, which is a great idea. But while they're hitting on a popular approach, I'd be curious if it will catch on more than these existing tools or ones built into frameworks."
Building microservices
Bourdakos's team began work on the parser while they created microservices for a travel agency demo. The demo required several different microservices that needed documention and several different languages that needed support.
"We started out just using regular OpenAPI, and we ended up with a lot of very big, YAML files, and we wanted to bring it in closer to our code," he said in an interview. "So we experimented with a library called swagger-jsdoc, which let you write Swagger/OpenAPI documentation inside your code inside js.comments."
However, the team pivoted to create its own library with a new syntax that still supported standard OpenAPI where they could write comments without having to worry about indentation.
"We built this with the mindset that it could be applied to other languages and microservice applications," Bourdakos said. "We have services in Python, Go and Node, which the js.comments were geared toward."
Dylan Schiemann, CEO of Living Spec in Gilbert, Ariz., and a Node.js expert, said he believes the IBM tool could be potentially useful.
What the OpenAPI Comment Parser does is take comments embedded inside source code and automatically convert it into OpenAPI format.
Dylan Schiemann CEO, Living Spec
The tool enables different components such as IDEs, web apps, and documentation viewers to read the same format and provide information for developers. Similarly, it provides a way for developers to share their documentation so it can get viewed in a variety of formats without generating multiple, different copies of documentation.
"What the OpenAPI Comment Parser does is take comments embedded inside source code and automatically convert it into OpenAPI format," Schiemann said. "The reason developers include comments in source code is that it makes it easier to keep the documentation synchronized with changes to the code. When things live in separate files it's easy to update the code and forget to update the accompanying documentation."
With the Node.js source code comments inline -- typically formatted using the JSDoc syntax, but optionally in YAML syntax -- all a developer needs to do is run the parser to generate a format that OpenAPI can understand.
"This makes it useful for Node.js developers that prefer writing inline comments to leverage the benefits of OpenAPI." Schiemann said.
Dylan Schiemann
