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.
