Java SpringBoot详解集成以及配置Swagger流程

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同

一、swagge简介

前后端分离:

后端U后端控制层，服务层，数据访问层【后端团队】

前端:前端控制层，视图层【前端团队】

前后端通过API进行交互

前后端相对独立且松耦合

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

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

前后端分离：前端测试后端接口:postman
后端提供接口，需要实时更新最新的消息及改动!

Swagger

号称世界上最流行的API框架
Restful Api 文档在线自动生成器 => API 文档与API 定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：API Documentation & Design Tools for Teams | Swagger

Java SpringBoot详解集成以及配置Swagger流程

二、SpringBoot集成Swagger

1、新建一个SpringBoot-web项目

2、添加Maven依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.9.2</version>
</dependency>

3、编写HelloController，测试确保运行成功！

Java SpringBoot详解集成以及配置Swagger流程

4、要使用Swagger，我们需要编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration
@EnableSwagger2        //开启Swagger2
public class SwaggerConfig {
  
}

5.访问测试：http://localhost:8081/swagger-ui.html,可以看到swagger的界面；

Java SpringBoot详解集成以及配置Swagger流程

三、配置Swagger

1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

//配置了Swagger的Docket的bean实例
  @Bean
  public Docket docket(){
      return new Docket(DocumentationType.SWAGGER_2);

  }

2、可以通过apiInfo()属性配置文档信息

  //配置文档信息
  private ApiInfo apiInfo() {
      Contact contact = new Contact("弟", "https://blog.csdn.net/weixin_48838340", "联系人邮箱");
      return new ApiInfo(
              "弟的Swagger学习文档", // 标题
              "学习演示如何配置Swagger", // 描述
              "v1.0", // 版本
              "https://blog.csdn.net/weixin_48838340", // 组织链接
              contact, // 联系人信息
              "Apach 2.0 许可", // 许可
              "许可链接", // 许可连接
              new ArrayList<>()// 扩展
      );
  }
}

3、Docket 实例关联上 apiInfo()

  @Bean
  public Docket docket(){
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
  }

4.重启项目

Java SpringBoot详解集成以及配置Swagger流程

四、配置扫描接口

构建Docket时通过select()方法配置怎么扫描接口。

  //配置了Swagger的Docket的bean实例
  @Bean
  public Docket docket(){
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //any() // 扫描所有，项目中的所有接口都会被扫描到
               // none() // 不扫描接口
      // withMethodAnnotation通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
      // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
              .apis(RequestHandlerSelectors.basePackage("com.longdi.swagger.controller"))
              //path()  过滤什么路径
              .paths(PathSelectors.ant("/longdi/**"))
              .build();
  };

五、配置Swagger开关

1、通过enable()方法配置是否启用swagger

  @Bean
  public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
              .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
              .apis(RequestHandlerSelectors.basePackage("com.longdi.swagger.controller"))
              // 配置如何通过path过滤,即这里只扫描请求以/longdi开头的接口
              .paths(PathSelectors.ant("/longdi/**"))
              .build();
  }

2.如何动态配置当项目处于test、dev环境时显示swagger

  @Bean
  public Docket docket(Environment environment) {
      // 设置要显示swagger的环境
      Profiles of = Profiles.of("dev", "test");
      // 判断当前是否处于该环境
      // 通过 enable() 接收此参数判断是否要显示
      boolean b = environment.acceptsProfiles(of);

      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
              .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
              .apis(RequestHandlerSelectors.basePackage("com.longdi.swagger.controller"))
              // 配置如何通过path过滤,即这里只扫描请求以/longdi开头的接口
              .paths(PathSelectors.ant("/longdi/**"))
              .build();
  }

六、配置API分组

1.如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

  @Bean
  public Docket docket1(Environment environment) {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
              .groupName("A") ;// 配置分组
      // 省略配置....
  }

2.配置多个分组只需要配置多个docket即可

Java SpringBoot详解集成以及配置Swagger流程

3.重启看到下面效果

Java SpringBoot详解集成以及配置Swagger流程

七、实体配置

1.新建一个实体类

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

Java SpringBoot详解集成以及配置Swagger流程

2.只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

  //只要我们的接口中，返回值中存在实体类，它就会被扫描到Swagger中
  @PostMapping(value="/user")
  public User getUser(){
      return new User();
  }

3.查看效果

Java SpringBoot详解集成以及配置Swagger流程

4.可以给请求的接口配置一些注释

  //Operation接口，不是放在类上的，是方法
  @ApiOperation("弟的接口")
  @GetMapping("/hello2")
  public String kuang(@ApiParam("这个名字会被返回")String username){
      return "hello"+username;
  }

Java SpringBoot详解集成以及配置Swagger流程