Swagger Editor 简介

1. 前言

大家好,今天为大家介绍 Swagger Editor。Swagger Editor 和 Swagger Codegen 不同,Swagger Editor 适用于一切规模的项目,话不多说,咱们直入正题。

2. 什么是 Swagger Editor ?

什么是 Swagger Editor 呢?在 Swagger 官网中是这么介绍的:

Swagger Editor 是一个开源编辑器,我们可以在这个开源编辑器上设计、描述和记录我们的 API 信息,通过 Swagger Editor 这个开源编辑器进行配置而生成的 API 是符合 RESTFUL API 规范的,并且 Swagger Editor 这款开源编辑器支持 Swagger 2.0 版本和 RESTFUL API 3.0 版本。 —官网

注意:这里提到的 OpenAPI 其实就是我们所谓的 RESTFUL API 规范,关于 RESTFUL API 规范我们已经在 Swagger 简介这一小节中做了详细的介绍,有不清楚的同学可以到该小节了解,这里不再赘述。

通过上面的介绍,说白了,Swagger Editor 就是一款提供了可以直接设计、描述和记录项目中所有的接口为 RESTFUL API 文档的开源编辑器,可以帮助我们提升项目开发效率。

3. 为什么要使用 Swagger Editor ?

那么我们为什么要使用 Swagger Editor 呢?

3.1 完善的 RESTFUL API 生成机制

对于任何规模大小的项目而言,无论是小项目还是大项目,都会涉及到项目接口的开发,而对于项目接口的管理,最常见的就是根据项目接口内容撰写项目接口文档,但是这种方式有一种显而易见的弊端。

当项目中接口开发的需求发生变化时,根据项目管理规范,我们需要首先修改之前撰写好的相应的接口文档,由于种种原因,导致我们的修改时机很慢而不能及时支撑该接口的修改交付工作,这就会产生冲突,就会不得已先进行接口的修改,后续再来修改接口文档了。

针对上述类似问题,如果我们使用 Swagger Editor 来对接口进行维护,就会大大降低这种问题出现的概率。

Swagger Editor 提供了强大的配置文件类型,例如我们熟知的 yml 配置源文件和少数的 json 配置源文件,针对这两种配置文件,Swagger Editor 内置了丰富的 RESTFUL API 属性,开发人员可以直接使用这些属性来描述项目中的接口信息,不需要专门再将接口修改为符合 RESTFUL API 规范而发愁了。

3.2 美观的界面显示效果

在第一章中,当我们在项目中集成了 Swagger 框架之后,运行项目之后会为我们生成 Swagger-ui 界面,我们都知道这个界面还是相对美观一些的,我们也可以直接在这个界面上浏览接口和其他信息。

Swagger Editor 在配置好之后的生成界面几乎是和 Swagger-ui 界面是一模一样的,而且 Swagger Editor 的生成界面允许我们边修改配置信息边查看修改结果,可以实时看到我们的修改结果。

这就表明,如果我们项目中的接口需求发生了变动,我们可以直接在 Swagger Editor 中修改相应的配置信息,并且可以实时看到修改结果,这对开发人员来说是一个’福音’。

4. 学习基础

  1. 学习 Swagger Editor 这个工具和 Swagger Codegen 一样,需要大家真实开发过项目并且对项目进行过简单的配置,并且使用的是 Java 7 或以上的 JDK 版本。

  2. 如果你是一名后端开发人员,那么相信你在学习 Swagger Editor 时会信手拈来。

5. 小结

Swagger Editor 其实就是一款可以为项目中的接口生成 RESTFUL API 规范界面的开源工具,其完善的 RESTFUL API 生成机制和美观的界面显示效果可以在提升项目接口的维护效率的同时增强接口文档的交互性,这也是 Swagger Editor 的核心魅力。