IBM的OpenAPI Comment Parser帮助开发人员编写文档API

IBM的OpenAPI Comment Parser为开发人员提供了一种新工具，可简化API的文档编制过程，从而使开发人员能够更轻松地使用它们。

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，我们专注于您永远不变的一个优先事项：质量！我们知道一遍又一遍地交付高质量的软件很复杂。因此，我们的工具旨在简化您的流程，同时与您使用的和将要使用的所有工具无缝协作。无论是Swagger，Cucumber，ReadyAPI，Zephyr，TestComplete还是更多，我们的工具都易于尝试、易于购买且易于集成。超过22000个组织的700万开发人员、测试人员和操作工程师正在使用我们的软件，其中包括Adobe，JetBlue和Microsoft等世界知名的创新者。无论您要去哪里，我们都会帮助您到达那里。在SmartBear上了解更多信息，或咨询在线客服以获取更多独家资料。

标签：

来源：慧都