IBM пусна нов “tool” за разработчиците, което има за цел да улесни писането на API документация. Проектът “The OpenAPI Comment Parser” е с лиценз Apache-2.0 и е наличен в GitHub.
“Няма значение дали става дума за приложение или уеб сайт, качествената документация е особено важна за успеха на проекта. Разработчиците се нуждаят от инструкции как да използват дадено API и начин да го изпробват. Добрата документация е от огромна полза и в двата случая”, това обяснява в Николас Бурдакос, IBM Developer Advocate в своя пост в Developer Blog-a на компанията.
Целта на The OpenAPI Comment Parser е даде възможност на програмистите да генерират OpenAPI спецификации директно от коментарите в техния код. Това неминуемо ще улесни разработчиците на софтуер и ще позволи поддържането на актуална документация, тъй като реално всичко необходимо за създаването на OpenAPI спецификациите ще бъде налично в кода.
Според екипа на IBM, новият формат ще намали с 50% писането на допълнителни спецификации.
Библиотеката се базира на Node.js, но Command Line интерфейсът (CLI) реално може да работи с всеки език за програмиране, който използва стила на коментиране, посочен по-долу:
/**
* GET /users/{userId}
* @summary Returns a user by ID.
* @pathParam {int64} userId - The user's ID.до
* @response 200 - OK
*/
Пример за използването на IBM OpenAPI Comment Parser за създаване на документация за Node.js API може да видите във видеото.
