IBM's OpenAPI Comment Parser helps devs document APIs – TechTarget

wp header logo 626

alex_aldo – Fotolia
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.
“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.”
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.
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.
For businesses contemplating the advantages and disadvantages of their applications living in a distributed cloud infrastructure,…
True FinOps maturity isn’t achievable without FinOps and cybersecurity team collaboration. The first step is building the …
Serverless apps come with unexpected challenges and sometimes they are nearly impossible to troubleshoot and optimize. Move away …
While plenty of developers entertain the idea of adopting a functional programming model, it’s important to first know exactly …
In this primer on SOLID, we’ll examine the five principles this development ideology embodies, the practices they encourage and …
Every software project proposal requires in-depth research into the technical aspects at play, but the business case for the …
The commercial backer of open source networking and security projects Cilium and Tetragon comes under Cisco’s control for …
Server-side WebAssembly hype peaked in late 2022, but a year later, its path to general availability for key features remains …
The lines between site reliability engineering and DevOps aren’t always clear. Building a harmonious relationship between the …
Whether you’re programming in Java or Python, compiled regex can significantly speed up your text manipulation routines.
Is shorter code too dense and hard to parse, or is it inherently more efficient and secure? Here’s why Python’s compact syntax …
Worried about your next employee performance review? Follow these six tips to get the most out of it.
Many organizations struggle to manage their vast collection of AWS accounts, but Control Tower can help. The service automates …
There are several important variables within the Amazon EKS pricing model. Dig into the numbers to ensure you deploy the service …
AWS users face a choice when deploying Kubernetes: run it themselves on EC2 or let Amazon do the heavy lifting with EKS. See …
All Rights Reserved, Copyright 2006 – 2024, TechTarget

Privacy Policy
Cookie Preferences
Do Not Sell or Share My Personal Information

source