如何利用 Swagger 消除前后端分离的障碍？

Posted 2021-04-30 架构之心

本文来自作者 蒋超 在 GitChat 上精彩分享的，「阅读原文」看看大家与作者交流了哪些问题

【不要错过文末彩蛋】

编辑 | 奥格瑞姆

前言

随着后端技术的日渐成熟和前端框架的异军突起，前后端分离几乎已经企业开发必须要选择的方向。

但是采用了 JSP、Struts2、SpringMVC 等技术的项目在实现前后端分离时，由于 Web 容器的使用，使得前端开发人员无法专注于前台展示，分离起来困难重重。

RESTful 架构的引入，让电脑端、移动端、第三方系统的数据交互和流程控制更加便捷，也使得前后端分离成为可能。

但是随着项目的推进，众多的 API 如果管理不当，在项目集成时，又将陷入泥潭。而 Swagger 的出现专注于为 API 提供可视化文档，便于前后端开发人员对接。

前后端分离很重要？

对于项目

前端界面注重展示效果，希望有更好的交互性和快速的响应。后台服务专注于提供数据，希望有稳定的性能，需要确保数据的安全，降低系统的瓶颈。

在业务逻辑复杂的系统里，最难维护的就是那些前后端混杂在一起的代码。我所在的项目组，搜索业务的代码原来是用 JSP 写的，代码风格相对随意，在数次艰难的 bug 修复后，终于全部废弃了。

对于公司

前后端界定不清，公司的招聘可能难度更大。full stack的工程师可遇而不可求，就算直接培养也很难使其在各个领域都成为大神。

而且 full stack 意味着他掌握的业务线越长，一旦离职，会对整个团队造成较大的影响。职责清楚，分工明确，意味着公司招聘更简单。

对于个人

前端人员有着自己的开发流程，有更适合的构建工具和测试方法，他们不希望用 Maven 构建项目、不希望用 Eclipse 编写代码，往往需要把用户体验放在第一位。

后端人员也有自己的开发习惯，他们不想用 Gulp 构建项目，也不会选择 WebStrom 调试代码，整天围绕着数据存贮与提取，数据计算，数据安全，往往把数据放在第一位。

前后端分离就是为了提高效率，提高项目的开发效率，提高公司的招聘效率，提高开发人员的学习效率。

然而，以API形式解耦前后端开发过程，通过 RESTFul 方式通信，项目集成将是绕不开的话题。开源项目 swagger 正是在这样的背景下因运而生。

Swagger 初步认知

Swagger 项目

Swagger 是很多产品的总称。包含最核心的规范 Swagger Specification，编辑器 Swagger Editor，图形界面 Swagger UI，代码生成器 Swagger Codegen，成熟的产品 SwaggerHub 等。

Swagger 的主要作用是描述 RESTful API，生成交互式文档，便于前后端开发人员查看请求信息和响应数据。

Swagger 与 OpenAPI

Swagger 项目最初由非营利组织Wordnik于2010年发起的， 之后于2015年转交给了 SmartBear，这家 SmartBear 公司专注于开发测试和性能工具。

随后 SmartBear 又在 Linux 基金会下创建了一个 OpenAPI Initiative(OAI) 项目，并捐献出了 Swagger。

由于 Google，IBM，Microsoft 等公司对 OpenAPI Initiative 的持续贡献，OAI 日渐成熟，Swagger 又被称之为 OpenAPI。

我们目前常用 Swagger 的版本为 Swagger 2.0，它的下一版不是 Swagger 3.0，而是 OpenAPI 3.0

Swagger 快速上手

要了解 Swagger，必须知道一些常用的 Swagger 规范，官方建议使用 JSON 格式或者 YAML 语法来编写这一规约，我更倾向于YAML，这种格式更容易书写和阅读。

Swagger Editor 编辑器

首先我们需要用到 Swagger Editor，你可以直接使用在线版本 http://editor.swagger.io/，或者在本地使用。如果电脑已经安装好了 Node.js，用下面的命令即可获得本地编辑器。

Node.js 不是必须的，你也可以直接下载 Swagger Editor 的源代码

https://github.com/swagger-api/swagger-editor。

解压以后，用本地浏览器打开 ./dist/index.htm l即可。

Swagger Editor 只是一款编辑器，学习 Swagger 不一定要用到它。你也可以用记事本或者Eclipse等工具编辑 Swagger 规约。

不过 Swagger Editor 有如下几个有点：1. 代码提示与代码高亮；2. 语法检查； 3. 实时预览，左边写code，右边实时生成UI。

Swagger Specification 规约

下面是我用 Swagger 规范写的一个「Hello World」，使用 Swagger Editor 编辑，可以很快得到下面的文档，而且可以在右侧看到生成的图形化界面。

首先是 YAML 格式，如 swagger.yml：

如果选择 JSON 格式，如 swagger.json：

{
    "swagger": "2.0",
    "info": {        "version": "1.0.0",        "title": "My Hello world",        "description": "description example"    },
    "schemes": [        "http"    ],
    "host": "test.com",
    "basePath": "/",
    "paths": {        "/hello": {            "get": {                "summary": "hello, world",                "description": "My first swagger.",                "parameters": [                    {                      "in": "query",                      "name": "name",                      "description": "The name of the person",                      "type": "string"                    }                ],                "responses": {                    "200": {                        "description": "A list of Person",                    }                }            }        }    }}

对比发现，YAML 格式看起来更舒服，写起来也更加便捷。当然，已经有很多工具可以实现 YAML-JSON 之间的转换，用自己喜欢的风格即可。

规范的内容本身很容易理解，配合 Swagger Editor 很容易能写出对用的API文档。如果需要更详细的说明，可以在官网的 doc 页面找到。

Swagger UI 交互式图形化界面

刚才得到的 Swagger 规约可以方便地在团队间编辑，传输，但是不够直观，于是有了Swagger-UI。

它是为基于 Swagger 规范的 API 生成基于纯粹 html，javascript，css 的在线可视化文档，同时也能成为 API 的在线测试工具。

你可以在 GitHub 上得到其源代码 https://github.com/wordnik/swagger-ui。其中 ./dist/* 中的文件是生成好的文件，可以直接使用，你也可以修改源代码，然后使用 Node 运行。

可以看到最新的版本于2017-09-15发布，该版本最大的优势就是支持OpenAPI 3.0

我们得到的文件 swagger-ui/dist/index.html 中有如下代码片段，将其中的url替换成自己的文件，如url: "swagger.yml"，用浏览器打开index.html，就能看到漂亮的文档说明。

<script>
window.onload = function() {

  // Build a system
  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })
  window.ui = ui
}
</script>

Swagger 与 Spring Boot

如果你的项目运用了 Microservice，引入了 Spring Boot，构建的 RESTful API 通过手工管理简直是噩梦。如今，Swagger 与 Spring Boot 的无缝对接，简直就是不愿写文档的猿类的福音。

需要的依赖

在 pom.xml 中需要引入支持 Swagger 所需要的依赖包。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version></dependency><dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version></dependency>

需要的配置

将 Swagger 整合到项目中，需要在启动类 Application.java 同级目录下创建一个配置类，名称任意，如 Swagger.java

@Configuration@EnableSwagger2public class Swagger {    @Bean
    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .select()                .apis(RequestHandlerSelectors.basePackage("com.gitchat.controller"))                .paths(PathSelectors.any())                .build();
    }

}

这里需要制定一个 basePackage( )，不然整个项目中所有的API都会生成文档，包括 Spring 自己的 service。

测试一下

启动 Spring Boot 程序后，访问：

http://localhost:8080/swagger-ui.html

将看到类似 Swagger UI 的效果。点击 Try it out 可以测试 API 的是否正常工作。

Swagger 与你有多近

基于前后端分离的契约，无论你是后端开发，前端开发，测试人员，你都可以体验到 Swagger 的众多好处。

• 生成交互式文档：一般开发人员容易忽视API文档，程序员最不喜欢的就是写文档，但是总是抱怨这个维护的程序怎么没有文档。

• 人类可读与机器可读：选择 JSON 和 YAML 格式作为 Swagger 的规范格式不是偶然的结果，这样可以让方便更多的用户编辑文档，分享分档，可以很方便地在各种编程语言之间直接调用或相互转换。

无论是手动编写 Swagger 规范，还是代码自动生成 Swagger 规约，漂亮的文档只是帮助我们更好的完成开发任务，Swagger 不是必须的，但，可能是必要的。

前后端分离了，接下来，就看你的了！

彩蛋

重磅 Chat

《高效学习，快速变现：不走弯路的五大学习策略》

分享人： 

Seaborn Lee，一名会在 B 站直播写代码，会玩杂耍球、弹 Ukulele、极限健身、跑步、写段子、画画、翻译、写作、演讲、培训的程序员。喜欢用编程实现自己的想法，在 android 市场上赚过钱，有多次创业经历。

擅长学习，习惯养成，时间管理。身体力行地影响他人做出积极的改变！目前就职于 ThoughtWorks，致力于传播快乐高效的编程理念。业余创立软件匠艺社区 CodingStyle.cn，组织超过30场技术活动。

Chat简介：

说到学习呀，真是头大哟：

• 碎片化，没有较长的连续时间来学习

• 难专注，捧起书，手机却在召唤：来呀，快活呀~ 反正有，大把时光~

• 做不到，看了很多书，生活中却做不到

• 然并卵，学了方法和工具，找不到使用场景

• 效率低，学习速度跟不上知识产生的速度

• 记不牢，学习速度赶不上遗忘速度

在这个知识泛滥、跨界竞争的年代，学习能力才是核心竞争力。你想想，过去一周，有没有哪一件工作是不需要学习就能完成的？

尽管如此重要，大部分人却没研究过学习这件事，以为上下班路上打开「得到」听本书，就是碎片时间终身学习者了。

想要免费参与本场 Chat ？

并在后台回复「高效学习」