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

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

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

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

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

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

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

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

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

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

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

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

但是，該團(tuán)隊(duì)致力于使用一種新語法創(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ù)。”

亞利桑那州吉爾伯特的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)用程序和文檔查看器）可以讀取相同的格式并為開發(fā)人員提供信息。同樣，它為開發(fā)人員提供了一種共享文檔的方式，因此可以以多種格式查看文檔，而無需生成多個(gè)不同的文檔副本。

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

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

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

關(guān)于SmartBear

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