IBM已發布了一個名為OpenAPI Comment Parser的新開源工具，以幫助開發人員在構建應用程序或網站時簡化API流程。

API需要良好的文檔，以便希望使用它們來構建服務，應用程序和網站的開發人員可以輕松地做到這一點。

IBM開發人員倡導者Nicholas Bourdakos在博客中說：“OpenAPI規范是用于定義和記錄API的開放標準。“OpenAPI規范可以生成出色的文檔，但是創建OpenAPI規范需要花費大量時間和精力來創建并保持最新。通常，OpenAPI規范最終會生成一個大型的、被遺忘的數千行文件。”

IBM創建了OpenAPI Comment Parser，以簡化API的文檔記錄過程。該工具使開發人員能夠從與其代碼內聯的注釋中生成OpenAPI規范。

Bourdakos在他的帖子中說：“當OpenAPI規范包含在代碼中時，開發人員很可能會在代碼更改時使其保持最新。”

IBM的OpenAPI Comment Parser是一種實用工具，旨在簡化和加快Node.js編寫的代碼的更新過程。它從開發人員的代碼中提取注釋，并生成一個OpenAPI文檔。開發人員可以在代碼內的注釋中編寫API詳細信息，而不必在YAML中創建OpenAPI文檔。

OpenAPI以前稱為Swagger。SmartBear于2015年收購了Swagger技術，并將該規范捐贈給了OpenAPI Foundation，該基金會將其更名為OpenAPI。但是，SmartBear保留了Swagger名稱，并且仍將其工具稱為Swagger，例如Swagger UI和Swagger編輯器。

SmartBear產品管理總監Stephen Mizell說，IBM的解析器是個好主意，SmartBear的工具可以為Java做類似的事情。

Mizell說：“這是一種非常流行的方法。”“IBM在這里使該注釋變得更通用，以便您可以使用任何支持其注釋樣式的語言來完成，這是一個好主意。但是，當他們采用一種流行的方法時，我很好奇它是否會流行不僅限于這些現有工具或框架中內置的工具。”

構建微服務

Bourdakos的團隊在為旅行社演示創建微服務時開始了解析器的工作。該演示需要幾種需要文檔的微服務和幾種需要支持的語言。

他在接受采訪時說：“我們開始只是使用常規的OpenAPI，最后得到了很多非常大的YAML文件，我們希望將其與我們的代碼更接近。”“因此，我們嘗試了一個名為swagger-jsdoc的庫，該庫使您可以在js.comments的代碼內編寫Swagger/OpenAPI文檔。”

但是，該團隊致力于使用一種新語法創建自己的庫，該語法仍支持標準OpenAPI，他們可以在其中編寫注釋而不必擔心縮進。

Bourdakos說：“我們本著可以將其應用于其他語言和微服務應用程序的思想來構建它。”“我們在Python，Go和Node中提供了js.comments面向的服務。”

亞利桑那州吉爾伯特的Living Spec首席執行官兼Node.js專家Dylan Schiemann表示，他相信IBM工具可能會很有用。

OpenAPI Comment Parser所做的是獲取嵌入在源代碼中的注釋，并將其自動轉換為OpenAPI格式。

——Dylan Schiemann，Living Spec首席執行官

該工具使不同的組件（如IDE，Web應用程序和文檔查看器）可以讀取相同的格式并為開發人員提供信息。同樣，它為開發人員提供了一種共享文檔的方式，因此可以以多種格式查看文檔，而無需生成多個不同的文檔副本。

Schiemann說：“OpenAPI Comment Parser所做的是獲取嵌入在源代碼中的注釋，并將其自動轉換為OpenAPI格式。”“開發人員在源代碼中包含注釋的原因是，它使文檔與代碼更改保持同步變得更加容易。當內容位于單獨的文件中時，很容易更新代碼而忘記更新隨附的文檔。”

使用內聯的Node.js源代碼注釋（通常使用JSDoc語法設置格式，但可以選擇使用YAML語法設置），開發人員所需要做的就是運行解析器以生成OpenAPI可以理解的格式。

“這對喜歡編寫內聯注釋以利用OpenAPI優勢的Node.js開發人員很有用。”Schiemann說。

關于SmartBear

在SmartBear，我們專注于您永遠不變的一個優先事項：質量！我們知道一遍又一遍地交付高質量的軟件很復雜。因此，我們的工具旨在簡化您的流程，同時與您使用的和將要使用的所有工具無縫協作。無論是，，，，TestComplete還是更多，我們的工具都易于嘗試、易于購買且易于集成。超過22000個組織的700萬開發人員、測試人員和操作工程師正在使用我們的軟件，其中包括Adobe，JetBlue和Microsoft等世界知名的創新者。無論您要去哪里，我們都會幫助您到達那里。在SmartBear上了解更多信息，或以獲取更多獨家資料。