用于生成 OAS 的注解库(以及来自 Swagger 用户的其他常见问题解答)

  2018 年 11 月 05 日

我们最近举办了一次免费的 Swagger 培训,将 Swagger 添加到现有 API:如何在规模上自动化“代码优先”到 OAS,其中我们研究了为现有 API 生成和托管 OpenAPI 规范 (OAS) 的不同工具和策略。

在网络研讨会期间,我们收到了大量关于团队在多种语言中开发 API 的不同选项的问题。我们还收到了关于 Swagger 工具如何提供帮助的问题,以及团队如何协调不同的 API 开发方法和 OAS 的问题。

作为网络研讨会的后续行动,我们想分享一些用于使用 OAS 的不同注解库的链接,并解答来自活动中 Swagger 用户的一些最重要的问题。

我们有使用 Java、C#、Python 等开发的 API。在哪里可以找到这些语言的最佳注解库?

OpenAPI 规范 (OAS) 和 Swagger 工具都有活跃的开发者社区,他们使用和开发新工具来支持您的 API 开发。Swagger 团队支持一些用于从现有 API 生成 OAS 的库,其余的由 OAS 社区维护:

您可以在此处探索其他支持 OAS 的开源工具。

在哪里可以阅读更多关于使用 Gradle 或 Maven 在 SwaggerHub 中存储定义的信息?

SwaggerHub 提供两个核心插件,用于自动化将生成的 OAS 定义导出到平台。

这些插件支持:

  • 从 SwaggerHub 下载/上传 API 定义。

  • API 定义的 JSON 和 YAML 格式。

  • 使用 API 密钥进行受限操作的身份验证(例如,将定义提交到私有组织)。

  • 默认连接到 SwaggerHub 云版本,或通过可选配置连接到本地 SwaggerHub 实例。

在此处了解有关 Gradle 插件的更多信息。

在此处了解有关 Maven 插件的更多信息。

我们使用 Swagger Codegen 项目来生成服务器存根,我们应该使用 SwaggerHub 来执行此操作的原因是什么?

SwaggerHub 是由 Swagger Codegen 项目背后的同一团队创建的。实际上,SwaggerHub 中的代码生成功能是在开源项目的贡献下运行的。

SwaggerHub 为您的团队提供了一个中心平台,可用于通过 OAS 协同开发 API。SwaggerHub 提供了一个单一平台来托管 OAS 定义、协作设计和记录您的 API,以及使用内置代码生成功能生成服务器存根和 SDK,而不是让各个开发人员在本地机器上安装的开源工具中独立工作或管理复杂的构建过程来支持大规模的构建。

SwaggerHub 还与您信任的 API 开发工具集成,无论您是需要推送到 API 网关、触发 Jenkins 构建还是与您的源代码控制主机同步,SwaggerHub 都提供了本地集成和插件来适应您的工作流程。

SwaggerHub 中 OAS 3.0 代码生成支持哪些语言?

我们正在继续在 SwaggerHub 中推出对新语言的支持。以下是有关 OAS 3.0 支持语言的最新更新:

客户端

  • Dynamic-html

  • Html

  • Html2

  • Java

  • Jaxrs-cxf-client

  • Kotlin-client

  • Php

  • Scala

  • Swift3

  • Swift4

  • Typescript-angular

服务器存根

  • Inflector

  • Jaxrs-jersey

  • Jaxrs-resteasy

  • Jaxrs-resteasy-eap

  • Scala-akka-http-server

  • Spring

当 API 发生更改时,规范会发生什么情况?它是否会自动更新 SwaggerHub 中现有的规范文档?

通过将源代码连接到像 SwaggerHub 这样的平台,可以将外部规范与作为构建过程一部分生成的版本保持一致。除此之外,SwaggerHub 还具有强大的版本控制系统,允许将多个团队、项目或更改智能地编目并存储在单一的事实来源中。

关于 API 网关部署,您是否能够在定义中直接添加验证,同时将其添加到规范中?

此功能通常不属于定义本身 – 我们会将生成的 OAS 传递给一个文件,该文件将执行一系列请求,并根据定义的响应对其进行验证。有一些以代码为中心的解决方案,例如 Swagger 测试模板 项目,以及一些允许导入 OAS 并轻松生成测试的 GUI 驱动解决方案,例如 ReadyAPI

是否可以将 SwaggerHub 注释转换为 JIRA 任务?

目前,我们没有直接集成到 JIRA。SwaggerHub 团队会根据用户和组织的反馈不断添加到支持的工具和平台列表中。

了解如何在规模上自动化您的“代码优先”方法。

您可以在此观看完整培训录像

当您准备好时,SwaggerHub 正在帮助各种规模的团队使用 OAS 协调其 API 开发——无论您是使用设计优先方法启动新项目,还是希望使用代码优先方法记录现有的一组 API。

立即免费开始使用。