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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

“這對(duì)喜歡編寫內(nèi)聯(lián)注釋以利用OpenAPI優(yōu)勢(shì)的Node.js開(kāi)發(fā)人員很有用。”Schiemann說(shuō)。

關(guān)于SmartBear

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