跳到主要内容

Swagger 简介

1. 前言​

大家好，今天我们开始一个新专题 — Swagger。

关于 Swagger 相信我们都在实际项目开发中使用过，它的核心知识点完全可以整理成一组专题来展开介绍，本专题我们重点讲解 Swagger 在基于 Java 生态框架的日常开发过中如何来应用。

本文我们主要先介绍一下 Swagger 是什么？有哪些特性？优缺点在哪？为什么我们需要在项目开发中应用 Swagger ？

2. 什么是 Swagger ？​

什么是 Swagger 呢？在 Swagger 官网中是这么介绍的：

Swagger 就是一种可以帮助我们简化 API 开发过程的工具。 — 官网

我们看到，这里提到了 API 这一术语，在业界，API 一般指的是：通过后端编码而开发出来的，且可以供其他用户所使用的一种专门对外暴露的数据传输接口，即我们可以通过编写 API 来达到和用户交互的目的。俗话说无规矩不成方圆，针对 API 业界也制定了一款标准，那就是 RESTFUL API 规范，下面我们来简单介绍一下什么是 RESTFUL API 规范：

RESTFUL 的全称是 Representational State Transfer，即表述性状态转换，或者我们可以通俗的理解为：一组具有约束条件和原则的规范。

也就是说：RESTFUL API 就是经过一组确定好的具有约束行为和统一原则的规范来规定 API 书写规则、命名规则、请求规则、响应规则的一种表述性方式。通过这个方式我们可以很好地理解具体 API 所代表的的业务场景和返回字段的含义。

通过上面的介绍，说白了，Swagger 就是一款可以简化项目 API 开发的工具，用来帮助我们通过最简单的途径来开发 RESTFUL API。

3. 为什么要使用 Swagger ？​

那么我们为什么要使用 Swagger 呢？

3.1 配置简单，容易上手​

如果我们需要在项目中使用 Swagger，那么我们只需要将 Swagger 的依赖集成到项目中去，然后通过一个简单的 Swagger 配置类即可开始使用了，不需要像其他工具那样还要繁琐的去配置 xml，即配置简单，容易上手。这为我们节省了大量的时间，使得我们可以把时间用在集中处理项目业务上，提升我们的开发效率。

3.2 界面美观，便于理解​

Swagger 通过内置 html 解析器的方式来实现将 RESTFUL API 显示在界面上供开发者查看，Swagger 提供的界面样式即简洁又美观，开发者可以很直观地看到自己所编写的 RESTFUL API 的请求方式、请求参数、返回格式以及所属业务组，如下图所示。

3.3 交互方便，完善沟通​

我们在开发 Java 项目的时候，主要的目的就是对外暴露我们的数据传输接口，来实现前后台数据交互的目的。

针对于我们编写的接口，往往我们需要撰写接口文档来说明具体接口所做的业务是什么，以及这个接口如何使用。这样在无形之中就加重了我们的工作内容，而有了 Swagger 之后，我们只需要在相应的地方添加 Swagger 的注解来对接口进行简单的说明，它就会帮助我们生成一份完整的接口说明，见上图。

这样一来我们就不用再编写一份几十页甚至几百页的接口文档了，提升了交互性能，同时也提升了前后台开发者的沟通效率。

总结：

Swagger 它是一个帮助开发人员来简化开发 RESTFUL API 的一款开发工具，其核心是基于 NPM 实现，在 Spring 项目中则是通过封装 SpringFox 依赖来完成对接口请求方式、请求参数、响应数据的加载，最终通过前端界面的方式来展现给用户。Swagger 具有简单、方便、高效的特性，用 Swagger 构建 RESTFUL API 可快速又方便。

4. Swagger 的版本说明​

Swagger 从 2011 年发布至今已经有 9 个年头，期间已经迭代升级了很多版本，现在最新的版本是 v3.18.3，每个版本都有不同的特性，下面主要介绍一个主要使用的版本和新版本的特性。

  • V1.0.1 - 1.0.13： 最初发布版本，基本已经很少使用了。
  • V2.X.X: 目前使用较多的版本，也是我们这个课程使用的版本。
  • V3.18.3: 目前发布的最新版本，2018 年 8 月 3 日发布的。主要是优化了接口组的使用方法、美化了 RESTFUL API 界面显示效果。最新版本可能会导致部分项目无法正常使用，这个时候需要回退到 2.X.X 版本即可。

5. Swagger 的优点​

  • 导出格式灵活 : 支持 Json 和 yml 来编写 API 文档，并且支持导出为 json、yml、markdown 等格式。
  • 跨语言支持性 : 只针对 API，而不针对特定语言的 API，很多自动生成 API 的工具基本都是只针对特定的 API。
  • 界面清晰易懂 : 界面清晰，无论是 Editor 的实时展示还是 Swagg-UI 界面的展示都十分人性化，简单明了。

6. Swagger 的缺点​

  • 无法自定义界面 : Swagger-UI 封装好了一套 Html 模板，任何 RESTFUL API 的展示形式只能遵循其格式，不能灵活修改。
  • 官方文档不全面 : Swagger 官方针对不同的模块提供了不同的介绍文档，但是缺乏系统的介绍，不利于新人学习。

7. 学习基础​

学习这门课程首先要有基于 Java 生态框架开发项目的经验，可以是使用 Java 框架开发项目的新人，也可以是具有丰富项目开发经验的老司机。

本套课程是用 SpringBoot 的方式，通过 Maven 包管理工具来快速使用 SpringBoot 框架，所以没有接触过 SpringBoot 框架和 Maven 包管理工具的同学请自行了解。

8. 小结​

本节是本套课程的开端，主要介绍了什么是 Swagger ，为什么使用 Swagger ，以及 Swagger 优缺点等。