Swagger

学习目标：

• 了解Swgger的作用和概念
• 了解前后端分离
• 在Springboot中集成Swgger

Swagger由来以及简介

前后端分离

Vue+Springboot

后端时代：前端只用管理静态页面：html给后端。模板引擎使用Jsp，jsp其实就类似于servlet，通过加载域对象达到动态获取的效果。

前后端分离式时代：

• 后端：后端控制层，服务层，数据访问层（Spring家族一统天下，不说了哈哈）

• 前端：前端控制器，视图层===》其实就算前端也开始工程化，三大框架就是一个标志，其显著的共同特点就是都有MV，而不单单只是传统的View即视图的意思，其显著特点在于前端开始也使用MVC思想，所谓的MVC,MVP,MVVM其实都是近似于此，当前端的接口一致，即跳转的路径一致，只要做的就算模拟数据，所以只要大家的需求保持一致，前端模拟的数据模型一致，当前后端都完成需求后，即可完成！！

  • 而模型在计算机程序中尤其是Web项目中，就可以说是数据，所以前端只要伪造数据，而且类型一致，所以伪造json数据即可

  打个不是很恰当的比喻：

  前后端分离的关系就就好比一把锁和钥匙
  

  钥匙要插的进去除了孔即接口一致以外，里面具体的纹理啊即模型要一致，那么前后端即可分离，后端是后端，没页面看不到效果，而前端开始用模具模拟后端，可以去模仿打一把，能不能用最后插进去一转，就可以知道了。(钥匙其实就相当于这个控制器和视图，能看见能实际用，哈哈哈强行一致)

• 前后端如何交互？===>调用一样的api，使用postman测试

• 产生问题，需求多变，导致前后接口同步存在时效性不一致，模是这个模，口不是这个口，肯定用不了。

所以噔噔蹬有问题怎么办？干掉提问题的人？噢不是解决问题，所以，产生了RestFul Api文档在线自动生成工具。没说错了，Swagger就算最靓的仔。

Swagger 演示

• 号称世界上最流行的Api框架
• RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新
• 直接运行，可以在线测试API接口
• 支持多种语言（java,php…）

官网：https://swagger.io/

用翻译插件翻译一下行啊干活方便了担任大摇大摆哈哈还是熟悉的一句话手动滑稽。点击探索，即可知道有什么工具可以用

项目中使用Swagger需要springfox

• Swagger2
• ui

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
    <scope>compile</scope>
</dependency>

最新的版本3.0sagger，springmvc使用上面的，版本号可以自己找合适的。

1.使用springfox-boot-starter整合

最新官方整合了一个启动器,springfox-boot-starter

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
<dependency>

当然在此之前也有也封装包，是前DD程序员封装的

<dependency>
	<groupId>com.spring4all</groupId>
	<artifactId>swagger-spring-boot-starter</artifactId>
	<version>1.9.1.RELEASE</version>
</dependency>

https://github.com/SpringForAll/spring-boot-starter-swagger

接下来演示：

1.使用swagger官方集成springboot启动器，创建第一个swagger项目

• 创建一个springboot的springweb项目

• 在pom文件中加入启动器依赖

  • io.springfox springfox-boot-starter 3.0.0

• 在书写一个hello入门程序

@RestController()
public class HelloController {

    @GetMapping("/hello")
    public String Hello(){
        return "hello";
    }
}

• 给类名和方法分别加上注解说明

  • @Api(tags="这是一个控制器类")
    @RestController()
    public class HelloController {
    
        @ApiOperation("这是一个hello方法")
        @GetMapping("/hello")
        public String Hello(){
            return "hello";
        }
    }
    

• 给启动类加上开启swagger2启动器启动注解，@EnableOpenApi

  以本项目为例子

  @EnableOpenApi
  @SpringBootApplication
  public class SwaggerqsApplication {
  
      public static void main(String[] args) {
          SpringApplication.run(SwaggerqsApplication.class, args);
      }
  
  }
  

• 启动

• 在客户端打开http://localhost:8080/swagger-ui/index.html，查看是否生效。

至此第一个swagger程序已经入门成功啦，因为swagger主要就算用于查看API接口。可在gitee上查看。

这里注意使用3.0的启动器，springboot版本不要低于2.2版本，笔者在测试的时候，似乎遇见了兼容问题。

还要注意两个点！一个是主类上的注解使用的@EnableOpenApi,开启OpenApi，有兴趣的可以点这个注解进去查看源码，他整合Springmvc配置等等的一系列配置。还有在类上面的@Api(tags=“这是一个控制器类”)这个注解记住，必须写tags，不要想着像SpringMVC那样的requestMapping括号里只有一个值就可以省略！！不可以！！必须把tags，加上去。

官方文档讲解的是使用配置文件的形式：

https://swagger.io/docs/specification/describing-parameters/

2. 接下来是直接使用：swagger2和ui整合

这一套的依赖是相对通用的，spring的web项目也是可以直接用的

还是讲一下在springboot下的整合方式

• 同样的还是创建项目一个springboot的springweb项目：

• 在pom导入以下依赖

• <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.0</version>
      <scope>compile</scope>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.0</version>
      <scope>compile</scope>
  </dependency>
  

• 创建一个hello包，其路径下再创建一个HelloController类，加上注解。

• package com.example.Hello;
  
  import io.swagger.annotations.Api;
  import io.swagger.annotations.ApiOperation;
  import org.springframework.web.bind.annotation.GetMapping;
  import org.springframework.web.bind.annotation.RestController;
  
  @Api(tags="这是一个控制器类")
  @RestController()
  public class HelloController {
  
      @ApiOperation("这是一个hello方法")
      @GetMapping("/hello")
      public String Hello(){
          return "hello";
      }
  }
  

• 再创建一个config包，创建Swaggerconfig自定义类，先不写东西：

  package com.example.config;
  
  import org.springframework.context.annotation.Configuration;
  import springfox.documentation.swagger2.annotations.EnableSwagger2;
  
  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
  }
  

加@Configuration，这个告诉springboot这是一个配置类，@EnableSwagger2这个是开始开启swagger2的意思，如果有多环境的测试尽量不要把@EnableSwagger2写再类上而是写在启动的主类上，实际上这里，这个config，要不要对这个案例都没影响，但实际上一般都会自定义一些除了一些文档的标识信息分组等自定义信息，所以是需要这个类的。

• 启动测试：http://localhost:8080/swagger-ui.html（注意这里和3使用的地址不一样）

默认UI风格有点不一样，布局基本一致，而不同的主要在于页面的显示样式不一样而且，我们还没去自定义url等，可以看见其写着这个是v2版本，而上面的则是v3版本的api-docs。

注意如果使用多环境配置，

官方的文档说的是使用配置文件的形式：（地址如下）

https://swagger.io/docs/specification/2-0/describing-parameters/

至此两个种使用依赖的方式演示了，根据自己的springboot选择合适吧！！代码源码托管在：https://gitee.com/calmtho/springbootstudy

之后还会更新相关的博客，如使用Java配置一些自定义内容，以及一些注解使用分享