跳到主要内容

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 优缺点等。