Swagger--介绍及SpringBoot集成Swagger

Posted 2021-06-22 Z && Y

01: Swagger–介绍及SpringBoot集成Swagger
02: Swagger–配置Swagger信息
03: Swagger–配置扫描接口及开关
04: Swagger–分组 & 接口注释
05: Swagger–接口测试&Swagger小结

1. Swagger--介绍及SpringBoot集成Swagger

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接
口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更
新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个
接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己
写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时
间推移，版本迭代，接口文档往往很容易就跟不上代码了。

---

1.1 Swagger是什么？它能干什么？

Swagger官网

• 随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
  • 前端 -> 前端控制层、视图层
  • 后端 -> 后端控制层、服务层、数据访问层
  • 前后端通过API进行交互
  • 前后端相对独立且松耦合
• 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

前后端分离产生的问题

前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险

1.2 Swagegr的优点

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 直接运行，在线测试API
• 支持多种语言 （如：Java，php等）

---

1.3 SpringBoot集成Swagger

要求：jdk 1.8 及以上 否则swagger2无法运行

---

1.3.1 创建一个SpringBoot的项目

---

1.3.2 导入相关依赖

注意：2.9.2版本使用的人最多，我们也尽量使用2.9.2版本吧

pom.xml

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>

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

---

1.3.3 编写HelloController，测试确保运行成功

HelloController.java

package com.tian.swagger.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * ClassName: HelloController
 * Description: 测试项目是否可以正常运行
 *
 * @author Administrator
 * @date 2021/6/5 21:05
 */
@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello() {
        return "hello";
    }
}

---

启动测试

说明项目没有问题

---

1.4 配置Swagger

SwaggerConfig.java

package com.tian.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * ClassName: SwaggerConfig
 * Description: Swagger的配置类
 *
 * @author Administrator
 * @date 2021/6/5 21:14
 */
@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}

---

1. 5 访问测试 ：

http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

---

---