swagger-01-swagger介绍

swagger

1.学习目标：

了解前后端分离
了解Swagger的作用和概念
在SpringBoot中集成Swagger

1.1 swagger由来

前后端分离，当前流行的开发模式

Vue+SpringBoot

早先的后端时代：前端只用管理静态页面；后端将html用模板引擎JSP进行开发
前后端分离式时代：
- 后端：后端控制层，服务层，数据访问层【后端团队】
- 前端：前端控制层，视图层【前端团队】
- - mock后端数据json,不需要后端，前端工程依旧能够跑起来
前端后如何交互？===>API
前后端相对独立，松耦合；
前后端甚至可以部署在不同的服务器上：
产生一个问题：

前后端集成联调，前端人员和后端人员无法做到“即使协商，尽早解决”，最终导致问题集中爆发

写完一个接口后，自己去创建接口文档，或者修改接口后修改接口文档。多了之后，你肯定会发生一个操作，那就是忘记了修改文档或者创建文档

解决方案：
- 首先指定schema[计划的提纲]，实时更新最新API,降低集成的风险：
- 早些年：指定word计划文档,提交到git
前后端分离：
- 前端测试后端接口：postman
- 后端提供接口，需要实时更新最新的消息及改动！

1.2 Swagger简介

号称世界上最流行的Api管理框架:一个在你写接口的时候自动帮你生成接口文档的工具，只要你遵循它的规范并写一些接口的说明注解即可。
RestFul Api文档在线自动生成工具=>Api文档与API定义同步更新

自动生成文档，只需要在难理解的接口或属性中使用注解进行标注，就能生成对应的接口文档。

自动更新文档，由于是动态生成的，所以如果你修改了接口，文档也会自动对应修改（如果你也更新了注解的话）。这样就不会发送我修改了接口，却忘记更新接口文档的情况。

支持在线调试，swagger提供了在线调用接口的功能。

直接运行，可以在线测试AP接口；
持多种语言：(java,Php.…)
官网：https://swagger.io/
在项目使用Swaggeri需要springfox;

springfox-swagger2
springfox-swagger-ui

缺点,

不能创建测试用例,只能提供一个简单的在线调试，如果你想存储你的测试用例，可以使用Postman或者YAPI这样支持创建测试用户的功能

要遵循一些规范，它不是任意规范的。比如说，你可能会返回一个json数据，而这个数据可能是一个Map格式的，那么我们此时不能标注这个Map格式的返回数据的每个字段的说明，而如果它是一个实体类的话，我们可以通过标注类的属性来给返回字段加说明。也比如说，对于swagger，不推荐在使用GET方式提交数据的时候还使用Body，仅推荐使用query参数、header参数或者路径参数，当然了这个限制只适用于在线调试。

没有接口文档更新管理，虽然一个接口更新之后，可能不会关心旧版的接口信息，但你“可能”想看看旧版的接口信息，例如有些灰度更新发布的时候可能还会关心旧版的接口。那么此时只能由后端去看看有没有注释留下了，所以可以考虑接口文档大更新的时候注释旧版的，然后写下新版的。

虽然现在Java的实体类中有不少模型，po,dto,vo等，模型的区分是为了屏蔽一些多余参数，比如一个用户登录的时候只需要username,password，但查权限的时候需要连接上权限表的信息，而如果上述两个操作都是使用了User这个实体的话，在文档中就会自动生成了多余的信息，这就要求了你基于模型来创建多个实体类，比如登录的时候一个LoginForm，需要用户-权限等信息的时候才使用User类。

综上，swagger功能已经满足我们的日常使用需要了，若是想协同开发或生成的测试用例等功能可以使用Apifox工具官网
Apifox是 API 文档、API 调试、API Mock、API 自动化测试一体化协作平台，定位 Postman + Swagger + Mock + JMeter
20分钟学会Apifox
Apifox 是接口管理、开发、测试全流程集成工具，使用受众为整个研发技术团队，主要使用者为前端开发、后端开发、测试人员。

1.3 SpringBoot集成Swagger

新建springboot-web项目，有一个默认请求/error
导入依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-test</artifactId>
    <scope>test</scope>
</dependency>
<!--springfox-swagger-->
<!--解决swagger3.0有问题需导入springfox-boot-starter-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

新建一个helloSwagger控制器，返回hello swagger!信息
配置Swagger:要使用swagger，我们必须对swagger进行配置，我们需要创建一个swagger的配置类，比如可以命名为SwaggerConfig.java

@Configuration // 标明是配置类
@EnableSwagger2  //开启swagger2功能 ,swagger老版本
public class SwaggerConfig {

}

啥也不配置，但有默认值！

测试运行，访问页面！http://localhost:8080/swagger-ui/index.html

swagger 3.0版本有问题,的有以下3种方式解决：

方式1：将swagger版本降为2.9.2
方式2：将springboot的版本降为2.5.7后重新启动项目，并将@EnableSwagger2注解改为@EnableOpenApi即可
方式3：springboot版本过高，springboot2.6更改了请求路径与与SpringMVC路径匹配规则，已经不是原来的AntPathMatcher了，改为了PathPatternParser。可能swagger3.0的一些地址还没作出相应的更新所以出错了。
- 3.0有问题的需要导入springfox-boot-starter这一个依赖，注解可换可不换@EnableOpenApi都行，用@EnableSwagger2也行
- 但需要在配置文件加上一句：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher


解决这个问题，使用springboot集成swagger3.0启动就报错：
org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException