swagger对比（swagger和swagger2）



OpenAPI / Swagger 相较于其他规范完善程度更高，生态更加完整，是目前 CODING 推荐的 API 设计语言。

OpenAPI 规范（OAS）是一种通用的、和编程语言无关的 API 描述规范，使人类和计算机都可以发现和理解服务的功能，而无需访问源代码、文档或针对接口进行嗅探。正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。

OpenAPI 始于 Swagger 规范，Swagger 规范已于 2015 年捐赠给 Linux 基金会后改名为 OpenAPI，并定义最新的规范为 OpenAPI 3.0。

CODING 目前支持以下版本导入：

• OpenAPI v3（OAS 3）
• Swagger v2

通常，设计 API 规范有两个方向，Design-First（设计优先） 或 Code-First（编码优先）

1. Design-First（设计优先）：

   即优先设计 API 规范，设计完成后再着手进行代码开发工作。

   采用 Design-First 就意味着，将设计 API 路由、参数等工作提前，后续整个软件开发的流程都需要围绕着 API 规范为核心，当然这需要有一定的设计经验的开发人员才能胜任。

   Design-First 有很多好处：

   点击查看更多参考

2. Code-First（编码优先）：

   即通过代码中关于 API 描述特性、注解或注释自动生成 API 描述文件的设计方式，如：JAVA 生态的 SpringFox。

   适合倾向于在代码上编写 API 规范，通过自动化设施自动生成文档的团队。

   Code-First 的优点：

   虽然 Code-First 省去了开发者设计 API 描述文件的阶段，提高了 API 开发者的效率，但是从整个团队的角度来看，效率并不一定提升了，反而有可能降低了效率。

   不同 API 开发者的经验和习惯的不同，极有可能在编码的过程中对 API 的限制条件考虑不全，又或者框架生成 API 文档的程序完善度不够，种种因素导致最终生成的 API 的描述无法达到理想标准。

   而很多 API 开发者习惯开发完成后才推送代码，并生成 API 文档，也导致了团队的进程阻塞于此，拖后了整个团队的开发进程。另一方面，API 在开发完成如果没有测试，很有可能导致 API 对接者在对接的过程中遇到重重阻碍。

   CODING 也希望各位开发者重视 API 设计的重要性，如果您喜欢 Code-First 设计方向，我们的建议是：

Design-First 和 Code-First 针对不同的场景有着各自的优势，不同团队对两者考虑的方向也不同，但是对 API 描述的完善不管是哪个方向都是最重要的。

下面我们将针对 Design-First 和 Code-First 两个方向的最佳实践作展开。

OpenAPI 进化到 v3 版本后，虽然规范非常完善，但对于首次上手的同学来说还是非常复杂，那么带有界面的编辑工具会成为最佳选择。

这里我们推荐使用 OpenAPI-GUI v3 来设计 API 描述文件，如下图所示。

OpenAPI-GUI v3 基本使用

OpenAPI-GUI v3 支持设计大多数常见情况的 API 规则，并且支持本地部署，非常适合新手，下面我们简单介绍一下 OpenAPI-GUI v3 的基本使用方式。

OpenAPI-GUI v3 的导航结构如上图所示。

首先，我们切换到 ，给 API 文档定义标题、描述、作者等基础信息。

接着，我们切换至 配置 API 各环境基础路径地址。

如果您的 API 需要经过鉴权（OAuth、APIKey 等），您可以切换到 配置响应的鉴权信息，如下图所示。

下面将开始设计 API 分组，点击切换到 ，对应的之后设计的接口可与分组相关联，并在文档中展示时，合并到对应分组栏目中。

为最主要的 API 设计界面，需要了解的是，CODING API 文档以 tag 分组，而该界面以路由+请求方法（Method）分组。

Description TAB 用于填写接口的标题、描述和关联 tag 信息，建议全部填写，若未填 Summary，API 文档将显示 API ID（OperationID），未关联 tag 将归属于默认分组。

Parameter 用于定义请求 Query、Header、Cookie 和路由参数规则，Location 可指定参数位置。

而在非 GET 请求方式（Method）方式下，如 POST / PATCH / PUT 等，Request Body 则用于定义请求 Body 的规则，如 Form 表单参数、纯 JSON 方式提交参数定义等。

对应的 Request Body 必须定义 Media-Type，可定义多个 Media-Type，API 服务器将根据该参数识别 Body 内容结构，如上图所示 即为纯 JSON 方式提交表单参数。

您可以复用实体，下面会讲到，或者直接编辑请求结构，点击后弹出如下图所示，可直接编辑。

需要注意的是，该弹窗弹出位置可能会在显示页面下方，需要滚动到下方才可看到。

切换到 Response TAB，我们可以定义接口响应返回的结构。

在这个界面可以增加多条响应结构，如 200、400、401 多个状态码有多重不同响应返回结构，或者同状态码下不同 Media-Type 不同返回结构。

点击编辑结构和 Request Body 类似，可定义响应数据结构规则。

切换到 Security TAB，可以配置接口的鉴权配置，由于编辑器未完善，您可在设计完成后通过导出 OpenAPI 描述文件，以源文件的形式修改 scope 范围（可参考下方进阶教程）。

由于 Docs / Links / Callbacks 在日常使用时不常用到，CODING API 文档暂不作展示。

在设计完毕后，您可点击右上角 Save 按钮保存修改，并点击 或者 复制或者下载 OpenAPI 描述文件。

接着，在 CODING API 文档导入并发布。

等待发布完毕后，点击详情页的文档地址，查看最终效果。

已有 OpenAPI 描述文件

如果您已有 OpenAPI 描述文件，或者您想先看一下效果，那么您可以切换到 TAB，将描述文件填入编辑框，或者点击 加载范例文件，并点击 加载描述文件。

进阶

虽然使用 OpenAPI-GUI v3 设计非常方便，但是对 OpenAPI 支持的并不完整，比如 Request & Response Example 无法在线编辑，这种场景下，我们就需要针对 OpenAPI 描述源文件进行编辑。

这里我们推荐使用 Swagger Editor 进行编辑，如下图所示：

Swagger Editor 是所见即所得的，并且如果写的语法有问题，会在对应段落显示错误提示，并说明错误原因，如下图所示：

相对于纯手写 OpenAPI 描述文件，Swagger Editor 有个贴心的功能，您可以很方便的通过可视化界面插入描述（如：path、operation 等）至编辑框中，如下图所示，

为了方便理解 OpenAPI v3 规范，我们在下方给出了 OpenAPI v3 的一般结构范例，对应的右边给出了字段的备注信息，方便对照：

该范例 CODING API 文档均支持展示

更详细的规范可参考：

• OpenAPI Map
• OpenAPI Specification

通过自动生成 OpenAPI 描述文件，我们可以很简单的接入 CODING API 文档的自动化流程，方便开发同学提交代码自动发布 API 文档。

• PHP：Swagger PHP
• Go：Go Swagger
• Python Flask：Flask RestPlus
• NodeJS Express：Swagger Node Express
• 点击查看

首先我们新建一个 SpringBoot 项目，添加 springfox 依赖：

上面 swagger-annotations 指定新版本操作，由于在非 String 的请求参数（如 Integer） @RequestParam 中指定 defaultValue 时，springfox 2.9.2 依赖的 swagger 包较旧，导致编译时报类型转换错误的问题，在新版已解决。

然后我们在 Application 中针对 Springfox 进行初始化配置操作，并定义 Swagger API 文档的全局描述信息：

接下来，我们可以开始设计 API 规则，以 PetController 为例，即 路由：

这里我们定义了两个路由，分别为：

• Query 请求参数

  -pagesize int 选填

  限制每页返回数量（最大限制：100）

  默认值 20

  -page int 选填

  页码

  默认值 1

• 响应结构

  -Pet 实体数组 array

• Header 参数

  -Accept string

  可选值 ，默认值 。

  媒体类型

• 路由参数

  -petId int

  宠物 ID

• 响应结构

  -Pet 实体 object

至此，我们完成了上述两个 API 的设计，无需提前实现代码逻辑，我们即可获得 Swagger 2.0 的描述文件，步骤如下：

该范例使用 Jetty 作为 Server

1. 启动应用

2. 打开浏览器访问

   其中 {port} 为配置的服务 WEB 端口

   返回的内容即为 Swagger 2.0 描述文件，如下图所示：

右键选择「存储为」保存至本地，可命名为 ，将该 Swagger 2.0 描述文件导入至 CODING 即可生成 API 文档，如下图所示：

生成的 API 文档效果如下图所示：

点击查看该范例的源代码。

更多 Springfox 的用法可参考官方文档

到此这篇swagger对比（swagger和swagger2）的文章就介绍到这了,更多相关内容请继续浏览下面的相关推荐文章，希望大家都能在编程的领域有一番成就！

版权声明：

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！

转载请注明出处，原文链接：https://www.xkablog.com/rfx/13864.html