1. 简介

1.1 认识Swagger2

Swagger 相当于一套规范，用来解决后端给的接口文档和实际情况不一致问题，只需要按照它的规范去定义接口及接口相关信息。再通过 Swagger 衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多做语言的客户端和服务端的代码，以及在线接口调试页面等等。

总结：Swagger 就是一个用来定义接口标准，接口规范，同时能根据你的代码自动生成接口说明文档的一个工具。

1.2 Swagger工具

Swagger Codegen ：通过Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也能生成多种语言的服务端和客户端代码。支持通过 jar 包、docker、node 等方式在本地化执行生成。也可以在后面的 Swagger Editor 中在线生成。
Swagger UI ：提供了一个可视化的 UI 页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署 UI 项目。
Swagger Editor ：类似于 Markdown 编辑器的编辑 Swagger 描述文件的编辑器，该编辑器支持实时预览描述文件的更新效果，也提供了在线编辑器和本地部署器俩种方式。Swagger Inspector ：感觉和 Postman 差不多，是一个可以对接口进行测试的在线版的postman。比如在 Swagger UI 里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub ：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

Springfox Swagger ：Spring 基于 Swagger 规范，可以将基于 SpringMVC 和 Spring Boot 项目的项目代码，自动生成 JSON 格式的描述文件。本身不是属于 Swagger 官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

2. 快速入门

2.1 引入Swagger2依赖

<!-- 引入swagger依赖 -->
<!-- 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>

2.2 编写Swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {
  /**
   * 编写Swagger2显示文档
   * @return
   */
  @Bean
  public Docket createRestApi() {
      return new Docket(DocumentationType.SWAGGER_2)
          .pathMapping("/")
          .select()
          // 扫描哪个接口的包
          .apis(RequestHandlerSelectors.basePackage("com.xuwei.controller"))
          .paths(PathSelectors.any())
          .build()
          .apiInfo(new ApiInfoBuilder()
                   .title("标题: SpringBoot 整合 Swagger 使用")
                   .description("详细信息: SpringBoot 整合 Swagger,详细信息......")
                   // 版本信息
                   .version("1.1")
                   // 开发文档的联系人
                   .contact(new Contact("yxw","http://www.baidu.com","1076372957@qq.com"))
                   .license("This Baidu License")
                   .licenseUrl("http://www.baidu.com")
                   .build());
  }
}

2.3 使用Swagger2常用注解

@Api：用在类上。
@ApiOperation：描述方法信息。

@ApiImplicitParams：描述方法参数信息。

/**
* @Description TODO
* @Author 闫旭威
* @Date 2021/2/26 14:52
*/
@RestController
@RequestMapping("/user")
@Api(tags = "用户服务相关接口描述")
public class IndexController {
  @GetMapping("/findAll")
  @ApiOperation(value = "查询所有用户接口", notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;用来查询所有用户信息的接口")
  public Map<String, Object> findAll() {
      Map<String, Object> map = new HashMap<>(16);
      map.put("success", "查询所有数据成功");
      map.put("status", true);
      return map;
  }
  /**
   * 普通参数保存
   * @param id
   * @param name
   * @return
   */
  @PostMapping("/save")
  @ApiOperation(value = "保存用户信息接口", notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;保存用户信息的接口")
  @ApiImplicitParams({
          @ApiImplicitParam(name = "id", value = "用户 id", dataType = "String", defaultValue = "21"),
          @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String", defaultValue = "白衣")
  })
  public Map<String, Object> save(String id, String name) {
      System.out.println("id = " + id);
      System.out.println("name = " + name);
      Map<String, Object> map = new HashMap<>(16);
      map.put("id", id);
      map.put("name", name);
      return map;
  }
  /**
   * RestFul风格保存
   * @param id
   * @param name
   * @return
   */
  @PostMapping("/save2/{id}/{name}")
  @ApiOperation(value = "保存用户信息接口", notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;保存用户信息的接口")
  @ApiImplicitParams({
          @ApiImplicitParam(name = "id", value = "用户 id", dataType = "String", defaultValue = "21"),
          @ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String", defaultValue = "白衣")
  })
  public Map<String, Object> save2(@PathVariable String id, @PathVariable String name) {
      System.out.println("id = " + id);
      System.out.println("name = " + name);
      Map<String, Object> map = new HashMap<>(16);
      map.put("id", id);
      map.put("name", name);
      return map;
  }
  /**
   * JSON格式使用：如果是RequestBody的方式，需要定义一个对象接收
   * @return
   */
  @PostMapping("/save3")
  @ApiOperation(value = "保存用户信息接口", notes = "<span style='color:red;'>描叙:</span>&nbsp;&nbsp;保存用户信息的接口")
  public Map<String, Object> save3(@RequestBody User user) {
      System.out.println("id = " + user.getId());
      System.out.println("name = " + user.getName());
      Map<String, Object> map = new HashMap<>(16);
      map.put("id", user.getId());
      map.put("name", user.getName());
      return map;
  }
}

2.4 浏览器访问

浏览器访问：localhost:8080/swagger-ui.html，使用 swagger2 进行测试。

3. 分组显示

3.1 修改配置类

实现分组显示：

/**
   * 分组显示：url为/api/.*的在同一个目录
   * @return
   */
  @Bean
  public Docket webApiConfig() {
      return new Docket(DocumentationType.SWAGGER_2)
              .groupName("webApi") //分组展示
              .apiInfo(webApiInfo())
              .select()
              .paths(Predicates.and(PathSelectors.regex("/api/.*")))
              .build();
  }
  /**
   * 分组显示：url为/admin/.*的在同一个目录
   * @return
   */
  @Bean
  public Docket adminApiConfig() {
      return new Docket(DocumentationType.SWAGGER_2)
              .groupName("adminApi")
              .apiInfo(adminApiInfo())
              .select()
              .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
              .build();
  }
  /**
   * 辅助方法：用来定义Swagger文档显示内容
   * @return
   */
  private ApiInfo webApiInfo() {
      return new ApiInfoBuilder()
              .title("网站的API文档")
              .description("本文档描述了谷粒学院的api接口定义")
              .version("1.0")
              .contact(new Contact("yxw","https://www.yuque.com/", "yxw666@163.com"))
              .build();
  }
  /**
   * 辅助方法：用来定义Swagger文档显示内容
   * @return
   */
  private ApiInfo adminApiInfo() {
      return new ApiInfoBuilder()
              .title("后台管理系统的API文档")
              .description("本文档描述了谷粒学院后台管理系统的admin接口定义")
              .version("1.0")
              .contact(new Contact("yxw","https://www.yuque.com/", "yxw666@163.com"))
              .build();
  }

3.2 浏览器访问

查看分组显示结果：

Java 企业级开发实践

集成Swagger2