TechTronBlog.com

Technology, Innovation, Collaboration
Menu
  • Features
  • Gadget
  • Mobile
  • Uncategorized

Daily Tech Updates Sent to your Email

Join our Newsletter
Home
Features
IBM creates an open source tool to simplify API documentation
Features

IBM creates an open source tool to simplify API documentation

August 17, 2020

OpenAPI Comment Parser for developers aims to make good API documentation easy to write and read.

openapi-comment-parser.jpg

Image: IBM

APIs are essential to programming, but they can get complicated. IBM has launched a new tool for developers that should make writing API documentation a bit easier: The OpenAPI Comment Parser.

“Developers need instructions on how to use your API and they need a way to try it out. Good documentation handles both,” IBM developer advocate Nicholas Bourdakos said in a blog post about the new developer tool.


Must-read developer content




OpenAPI is a specification that was built as a language-agnostic interface for RESTful APIs, “which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection,” said API tool maintainer Swagger.

The Comment Parser is designed to work around a problem that Bourdakos said is common for developers working with the OpenAPI specification: OpenAPI specs for recording comments have to be built and maintained manually, which means they often get forgotten and become bloated and useless. 

SEE: Quick Glossary: DevOps (TechRepublic Premium)

“The goal of OpenAPI Comment Parser is to give developers a way to generate this OpenAPI spec from comments inline with their code,” Bourdakos said. 

The OpenAPI spec under the Comment Parser lives inside the code, broken up into smaller pieces that can be more easily updated because the need to go searching through a giant spec file is eliminated. “On average, this new format has been shown to reduce the amount of spec needed to be written by 50%,” Bourdakos said.

Bourdakos gives a demonstration of how the OpenAPI Comment Parser works in a video, where he uses Docusaurus along with the Comment Parser to make an API documentation site. The graphical layout of the site pulls OpenAPI spec comments from his code and lays it out in an easy-to-see fashion using markdown. 

The Docusaurus interface makes comments easy to see, search, and review, and because they’re written in-line with the code, thanks to the Parser, a developer who needs to make changes to a particular section can simply update that comment. 

The Comment Parser, Bourdakos said, is designed to make developer’s lives easier by eliminating superfluous documentation code. Not only does this save time, but it also makes the code itself more manageable, he said.

SEE: Top 5 programming languages for systems admins to learn (free PDF) (TechRepublic)

Documentation generation by the Comment Parser can also be used to test the API, so developers can spend “less time waiting for a frontend to be built or having to rely on other tools in order to test drive their API,” Bourdakos said.

IBM’s OpenAPI Comment Parser was built for use with Node.js, but its command line interface will work with any language that uses a similar comment style. IBM will be adding support for additional “popular languages” in the future. 

In the meantime, Devs that use Node.js or a language with a similar commenting format can now try the OpenAPI Comment Parser.







Developer Essentials Newsletter


From the hottest programming languages to the jobs with the highest salaries, get the developer news and tips you need to know.
Weekly




Sign up today





Share
Tweet
Email
Prev Article
Next Article

Related Articles

https://www.techrepublic.com/article/how-phishing-attacks-have-exploited-the-us-small-business-administration/#ftag=RSS56d97e7

How phishing attacks have exploited the US Small Business Administration

https://www.techrepublic.com/article/future-of-farming-ai-enabled-harvest-robot-flexes-new-dexterity-skills/#ftag=RSS56d97e7

Future of farming: AI-enabled harvest robot flexes new dexterity skills

About The Author

Leave a Reply

Cancel reply

Recent Posts

  • New tech and gadgets you absolutely can’t miss
  • Razer Pro Click ergonomic wireless mouse maximizes your productivity
  • Lume Cube Panel Mini Bicolor LED Light provides on-the-go lighting for photographers
  • LINKA LEO GPS Smart Bike Lock can track your bicycle’s movements in more than 100 countries
  • Razer Pro Glide soft mouse mat cushions your hand during use

Recent Comments

    Archives

    • August 2020

    Categories

    • Features
    • Gadget
    • Mobile
    • Uncategorized

    Meta

    • Log in
    • Entries feed
    • Comments feed
    • WordPress.org

    TechTronBlog.com

    Technology, Innovation, Collaboration
    Copyright © 2021 TechTronBlog.com
    Theme by MyThemeShop.com

    Ad Blocker Detected

    Our website is made possible by displaying online advertisements to our visitors. Please consider supporting us by disabling your ad blocker.

    Refresh