IBM已發(fā)布了一個名為OpenAPI Comment Parser的新開源工具，以幫助開發(fā)人員在構(gòu)建應(yīng)用程序或網(wǎng)站時簡化API流程。

API需要良好的文檔，以便希望使用它們來構(gòu)建服務(wù)，應(yīng)用程序和網(wǎng)站的開發(fā)人員可以輕松地做到這一點。

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

IBM創(chuàng)建了OpenAPI Comment Parser，以簡化API的文檔記錄過程。該工具使開發(fā)人員能夠從與其代碼內(nèi)聯(lián)的注釋中生成OpenAPI規(guī)范。

Bourdakos在他的帖子中說：“當(dāng)OpenAPI規(guī)范包含在代碼中時，開發(fā)人員很可能會在代碼更改時使其保持最新?！?/span>

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

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

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

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

構(gòu)建微服務(wù)

Bourdakos的團(tuán)隊在為旅行社演示創(chuàng)建微服務(wù)時開始了解析器的工作。該演示需要幾種需要文檔的微服務(wù)和幾種需要支持的語言。

他在接受采訪時說：“我們開始只是使用常規(guī)的OpenAPI，最后得到了很多非常大的YAML文件，我們希望將其與我們的代碼更接近?！薄耙虼耍覀儑L試了一個名為swagger-jsdoc的庫，該庫使您可以在js.comments的代碼內(nèi)編寫Swagger/OpenAPI文檔?！?/span>

但是，該團(tuán)隊致力于使用一種新語法創(chuàng)建自己的庫，該語法仍支持標(biāo)準(zhǔn)OpenAPI，他們可以在其中編寫注釋而不必?fù)?dān)心縮進(jìn)。

Bourdakos說：“我們本著可以將其應(yīng)用于其他語言和微服務(wù)應(yīng)用程序的思想來構(gòu)建它。”“我們在Python，Go和Node中提供了js.comments面向的服務(wù)?！?/span>

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

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

——Dylan Schiemann，Living Spec首席執(zhí)行官

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

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

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

“這對喜歡編寫內(nèi)聯(lián)注釋以利用OpenAPI優(yōu)勢的Node.js開發(fā)人員很有用?！?/span>Schiemann說。

關(guān)于SmartBear

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