Spring Boot整合Swagger2

Posted 程序员涂陌

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Spring Boot整合Swagger2相关的知识，希望对你有一定的参考价值。

 


Spring Boot2整合Swagger2.9.2

在学习或开发一些项目时，常会遇到前端需要一份详细的后端API说明文档，因此Swagger的诞生就是为了实现这个需求的。Swagger提供了非常好看的界面，并且提供了API测试工具，类似Postman工具的功能。

所以，这次我们就学习一下如何在SpringBoot项目中部署Swagger2

起步

依赖导入

相信你注意到了，这里我为什么特意强调Swagger的版本，截止2019-2-27，Swagger的最新版是2.9.2，而很多教程中Swagger还是老版本，就造成了很多注解报错或和图片中的不一样。

在这里，我采用了如下版本：

  • Spring Boot 2.1.3.RELEASE

  • Swagger 2.9.2

导入Swagger2依赖：

 
   
   
 
    
  
    
    
  
  1. <dependency>
    2. 
  
    
    
  
  2.  <groupId>io.springfox</groupId>
    3. 
  
    
    
  
  3.  <artifactId>springfox-swagger2</artifactId>
    4. 
  
    
    
  
  4.  <version>2.9.2</version>
    5. 
  
    
    
  
  5. </dependency>
    6. 
  
    
    
  
  6. <dependency>
    7. 
  
    
    
  
  7.  <groupId>io.springfox</groupId>
    8. 
  
    
    
  
  8.  <artifactId>springfox-swagger-ui</artifactId>
    9. 
  
    
    
  
  9.  <version>2.9.2</version>
    10. 
  
    
    
  
  10. </dependency>
    11.

如果你用过Swagger2高版本就知道总会出现错误： java.lang.NumberFormatException:Forinputstring:""，说是 example设置问题，但是最有效的解决办法是添加如下依赖：

 
   
   
 
    
  
    
    
  
  1. <!-- 使用Swagger2最新版本2.9.2避免NumberFormatException错误要引入下列两个依赖 -->
    2. 
  
    
    
  
  2. <dependency>
    3. 
  
    
    
  
  3.  <groupId>io.swagger</groupId>
    4. 
  
    
    
  
  4.  <artifactId>swagger-annotations</artifactId>
    5. 
  
    
    
  
  5.  <version>1.5.21</version>
    6. 
  
    
    
  
  6. </dependency>
    7. 
  
    
    
  
  7. <dependency>
    8. 
  
    
    
  
  8.  <groupId>io.swagger</groupId>
    9. 
  
    
    
  
  9.  <artifactId>swagger-models</artifactId>
    10. 
  
    
    
  
  10.  <version>1.5.21</version>
    11. 
  
    
    
  
  11. </dependency>
    12.

配置

新建 /config/SwaggerConfig.java配置类：

 
   
   
 
    
  
    
    
  
  1. @Configuration
    2. 
  
    
    
  
  2. @EnableSwagger2
    3. 
  
    
    
  
  3. public class SwaggerConfig {
    4. 
  
    
    
  

    5. 
  
    
    
  
  5.  @Bean
    6. 
  
    
    
  
  6.  public Docket createRestApi() {
    7. 
  
    
    
  
  7.  return new Docket(DocumentationType.SWAGGER_2)
    8. 
  
    
    
  
  8.  .apiInfo(apiInfo())
    9. 
  
    
    
  
  9.  .select()
    10. 
  
    
    
  
  10.  .apis(RequestHandlerSelectors.basePackage("cn.tycoding.controller"))
    11. 
  
    
    
  
  11.  .paths(PathSelectors.regex("/.*"))
    12. 
  
    
    
  
  12.  .build();
    13. 
  
    
    
  
  13.  }
    14. 
  
    
    
  

    15. 
  
    
    
  
  15.  private ApiInfo apiInfo() {
    16. 
  
    
    
  
  16.  return new ApiInfoBuilder()
    17. 
  
    
    
  
  17.  .title("Spring Boot中使用使用Swagger2构建RESTful API")
    18. 
  
    
    
  
  18. 
  
    
    
  
  19.  .termsOfServiceUrl("http://tycoding.cn/")
    20. 
  
    
    
  
  20.  .contact(new Contact("tycoding", "https://tycoding.cn", ""))
    21. 
  
    
    
  
  21.  .version("v1.0")
    22. 
  
    
    
  
  22.  .build();
    23. 
  
    
    
  
  23.  }
    24. 
  
    
    
  
  24. }
    25.

这些都是Swagger全局配置信息，其中最需要注意的有以下几点：

看 PathSelectors类源码：

 
   
   
 
    
  
    
    
  
  1. public class PathSelectors {
    2. 
  
    
    
  
  2.  private PathSelectors() {
    3. 
  
    
    
  
  3.  throw new UnsupportedOperationException();
    4. 
  
    
    
  
  4.  }
    5. 
  
    
    
  

    6. 
  
    
    
  
  6.  public static Predicate<String> any() {
    7. 
  
    
    
  
  7.  return Predicates.alwaysTrue();
    8. 
  
    
    
  
  8.  }
    9. 
  
    
    
  

    10. 
  
    
    
  
  10.  public static Predicate<String> none() {
    11. 
  
    
    
  
  11.  return Predicates.alwaysFalse();
    12. 
  
    
    
  
  12.  }
    13. 
  
    
    
  

    14. 
  
    
    
  
  14.  public static Predicate<String> regex(final String pathRegex) {
    15. 
  
    
    
  
  15.  return new Predicate<String>() {
    16. 
  
    
    
  
  16.  public boolean apply(String input) {
    17. 
  
    
    
  
  17.  return input.matches(pathRegex);
    18. 
  
    
    
  
  18.  }
    19. 
  
    
    
  
  19.  };
    20. 
  
    
    
  
  20.  }
    21. 
  
    
    
  

    22. 
  
    
    
  
  22.  public static Predicate<String> ant(final String antPattern) {
    23. 
  
    
    
  
  23.  return new Predicate<String>() {
    24. 
  
    
    
  
  24.  public boolean apply(String input) {
    25. 
  
    
    
  
  25.  AntPathMatcher matcher = new AntPathMatcher();
    26. 
  
    
    
  
  26.  return matcher.match(antPattern, input);
    27. 
  
    
    
  
  27.  }
    28. 
  
    
    
  
  28.  };
    29. 
  
    
    
  
  29.  }
    30. 
  
    
    
  
  30. }
    31.

发现它能支持4中方式按照路径生成API文档：1.任何路径都生成；2.任何路径都不生成；3.正则匹配路径；4.ant模式匹配。

上面我们就是配置的正则匹配路径，按照正则标准，Swagger扫描对应的API接口并生成文档。

如果你还有疑惑，可以先看一下项目整体结构：

（八）Spring Boot整合Swagger2

详解

既然都用到了Swagger，那就必然要遵循Restful接口规范，最基本的规范：

前端请求方法 对应后端操作
POST 新增
PUT 更新
GET 查询
DELETE 删除

更多的Restful接口规范请自行百度。

通常在前后端分离项目中，后端仅负责接收和传递JSON数据，所以，我们这样创建一个Controller：

 
   
   
 
    
  
    
    
  
  1. @RestController
    2. 
  
    
    
  
  2. @RequestMapping("/article")
    3. 
  
    
    
  
  3. public class ArticleController {
    4. 
  
    
    
  
  4. }
    5.

  • @RestController是 @ResponseBody+ @Controller，其控制器类下的所有方法的返回值都将被Spring转换成JSON格式。

编写代码

Article

为了模拟实际中业务，这里创建一个实体类 Article.java

 
   
   
 
    
  
    
    
  
  1. public class Article implements Serializable {
    2. 
  
    
    
  

    3. 
  
    
    
  
  3.  private Long id; //文章ID
    4. 
  
    
    
  
  4.  private String name; //文章名称
    5. 
  
    
    
  
  5.  private String title; //文章标题
    6. 
  
    
    
  
  6.  private Date createTime; //创建时间
    7. 
  
    
    
  

    8. 
  
    
    
  
  8.  ...//省略getter/setter
    9. 
  
    
    
  
  9. }
    10.

Result

通常，Controller返回的数据都应该被封装在一个结果类中，目的是保证所有请求返回结果都有固定的响应格式，比如：状态码、状态信息、返回结果。所以我们简单封装一个结果类：

 
   
   
 
    
  
    
    
  
  1. public class ResponseCode {
    2. 
  
    
    
  

    3. 
  
    
    
  
  3.  private Long code;
    4. 
  
    
    
  
  4.  private String msg;
    5. 
  
    
    
  
  5.  private Object data;
    6. 
  
    
    
  

    7. 
  
    
    
  
  7.  public ResponseCode() {
    8. 
  
    
    
  
  8.  }
    9. 
  
    
    
  

    10. 
  
    
    
  
  10.  public ResponseCode(Long code, String msg, Object data) {
    11. 
  
    
    
  
  11.  this.code = code;
    12. 
  
    
    
  
  12.  this.msg = msg;
    13. 
  
    
    
  
  13.  this.data = data;
    14. 
  
    
    
  
  14.  }
    15. 
  
    
    
  

    16. 
  
    
    
  
  16.  public static ResponseCode ok(String msg) {
    17. 
  
    
    
  
  17.  return new ResponseCode(200L, msg, null);
    18. 
  
    
    
  
  18.  }
    19. 
  
    
    
  

    20. 
  
    
    
  
  20.  public static ResponseCode ok(String msg, Object data) {
    21. 
  
    
    
  
  21.  return new ResponseCode(200L, msg, data);
    22. 
  
    
    
  
  22.  }
    23. 
  
    
    
  

    24. 
  
    
    
  
  24.  ...//省略getter/setter
    25. 
  
    
    
  
  25. }
    26.

ArticleController

完善控制器类，模拟常见的CRUD业务：

 
   
   
 
    
  
    
    
  
  1. @RestController
    2. 
  
    
    
  
  2. @RequestMapping("/article")
    3. 
  
    
    
  
  3. public class ArticleController {
    4. 
  
    
    
  
  4.  private Logger logger = LoggerFactory.getLogger(this.getClass());
    5. 
  
    
    
  

    6. 
  
    
    
  
  6.  @GetMapping(value = "/{id}", produces = "application/json")
    7. 
  
    
    
  
  7.  public ResponseCode findById(@PathVariable Long id) {
    8. 
  
    
    
  
  8.  logger.info("查询文章信息，查询的文章ID是==> {}", id);
    9. 
  
    
    
  
  9.  Article article = new Article(1L, "Swagger", "SpringBoot整合Swagger2", new Date());
    10. 
  
    
    
  
  10.  return ResponseCode.ok("查询成功", article);
    11. 
  
    
    
  
  11.  }
    12. 
  
    
    
  

    13. 
  
    
    
  
  13.  @DeleteMapping(value = "/{id}", produces = "application/json")
    14. 
  
    
    
  
  14.  public ResponseCode delete(@PathVariable Long id) {
    15. 
  
    
    
  
  15.  logger.info("删除文章信息，删除的文章ID是==> {}", id);
    16. 
  
    
    
  
  16.  return ResponseCode.ok("删除成功");
    17. 
  
    
    
  
  17.  }
    18. 
  
    
    
  

    19. 
  
    
    
  
  19.  @PostMapping(value = "/", produces = "application/json")
    20. 
  
    
    
  
  20.  public ResponseCode save(@RequestBody Article article) {
    21. 
  
    
    
  
  21.  logger.info("保存文章信息，文章内容==> {}", article);
    22. 
  
    
    
  
  22.  return ResponseCode.ok("保存成功");
    23. 
  
    
    
  
  23.  }
    24. 
  
    
    
  

    25. 
  
    
    
  
  25.  @PutMapping(value = "/", produces = "application/json")
    26. 
  
    
    
  
  26.  public ResponseCode update(@RequestBody Article article) {
    27. 
  
    
    
  
  27.  logger.info("更新文章信息，更新内容==> {}", article);
    28. 
  
    
    
  
  28.  return ResponseCode.ok("更新成功");
    29. 
  
    
    
  
  29.  }
    30. 
  
    
    
  
  30. }
    31.

如上，我们完成了基础操作。

测试

启动项目，访问 localhost:8080/swagger-ui.html：

（八）Spring Boot整合Swagger2

是不是很神奇呢，这么炫酷漂亮的界面Swagger已经帮我们写好了，根据刚才配置的 .apis(RequestHandlerSelectors.basePackage("cn.tycoding.controller"))Swagger扫描到了 ArticleController这个控制器类，根据刚才配置的 .paths(PathSelectors.regex("/.*"))Swagger扫描了这个控制器的所有请求映射路径，并且生成API文档。

更神奇的在这里：

任意点开一个接口，点击左侧的Try it out，可以直接测试这个接口，就像Postman工具一样，并且旗下有丰富的接口文档信息

（八）Spring Boot整合Swagger2

可以看到我们模拟的接口请求成功，并且返回了响应数据。

进阶配置

修改 ArticleController

 
   
   
 
    
  
    
    
  
  1. @RestController
    2. 
  
    
    
  
  2. @RequestMapping("/article")
    3. 
  
    
    
  
  3. @Api(value = "ArticleController", tags = {"文章管理接口"})
    4. 
  
    
    
  
  4. public class ArticleController {
    5. 
  
    
    
  
  5.  private Logger logger = LoggerFactory.getLogger(this.getClass());
    6. 
  
    
    
  

    7. 
  
    
    
  
  7.  @GetMapping(value = "/{id}", produces = "application/json")
    8. 
  
    
    
  
  8.  @ApiOperation(value = "查询文章详情", notes = "文章ID大于0")
    9. 
  
    
    
  
  9.  @ApiImplicitParam(name = "id", value = "文章编号", required = true, dataType = "Long")
    10. 
  
    
    
  
  10.  public ResponseCode findById(@PathVariable Long id) {
    11. 
  
    
    
  
  11.  logger.info("查询文章信息，查询的文章ID是==> {}", id);
    12. 
  
    
    
  
  12.  Article article = new Article(1L, "Swagger", "SpringBoot整合Swagger2", new Date());
    13. 
  
    
    
  
  13.  return ResponseCode.ok("查询成功", article);
    14. 
  
    
    
  
  14.  }
    15. 
  
    
    
  

    16. 
  
    
    
  
  16.  @DeleteMapping(value = "/{id}", produces = "application/json")
    17. 
  
    
    
  
  17.  @ApiOperation(value = "删除文章")
    18. 
  
    
    
  
  18.  @ApiImplicitParam(name = "id", value = "文章编号", required = true, dataType = "Long")
    19. 
  
    
    
  
  19.  public ResponseCode delete(@PathVariable Long id) {
    20. 
  
    
    
  
  20.  logger.info("删除文章信息，删除的文章ID是==> {}", id);
    21. 
  
    
    
  
  21.  return ResponseCode.ok("删除成功");
    22. 
  
    
    
  
  22.  }
    23. 
  
    
    
  

    24. 
  
    
    
  
  24.  @PostMapping(value = "/", produces = "application/json")
    25. 
  
    
    
  
  25.  @ApiOperation(value = "保存文章")
    26. 
  
    
    
  
  26.  @ApiImplicitParam(name = "article", value = "文章信息实体", required = true, dataType = "Article", paramType = "body")
    27. 
  
    
    
  
  27.  public ResponseCode save(@RequestBody Article article) {
    28. 
  
    
    
  
  28.  logger.info("保存文章信息，文章内容==> {}", article);
    29. 
  
    
    
  
  29.  return ResponseCode.ok("保存成功");
    30. 
  
    
    
  
  30.  }
    31. 
  
    
    
  

    32. 
  
    
    
  
  32.  @PutMapping(value = "/", produces = "application/json")
    33. 
  
    
    
  
  33.  @ApiOperation(value = "更新文章")
    34. 
  
    
    
  
  34.  @ApiImplicitParam(name = "article", value = "文章信息实体", required = true, dataType = "Article", paramType = "body")
    35. 
  
    
    
  
  35.  public ResponseCode update(@RequestBody Article article) {
    36. 
  
    
    
  
  36.  logger.info("更新文章信息，更新内容==> {}", article);
    37. 
  
    
    
  
  37.  return ResponseCode.ok("更新成功");
    38. 
  
    
    
  
  38.  }
    39. 
  
    
    
  
  39. }
    40.

修改 Article.java

 
   
   
 
    
  
    
    
  
  1. @ApiModel(value = "Article", description = "文章实体对象")
    2. 
  
    
    
  
  2. public class Article implements Serializable {
    3. 
  
    
    
  

    4. 
  
    
    
  
  4.  /**
    5. 
  
    
    
  
  5.  * @ApiModelProperty 用于描述实体字段
    6. 
  
    
    
  
  6.  * value: 字段说明
    7. 
  
    
    
  
  7.  * name: 重写字段名称
    8. 
  
    
    
  
  8.  * dataType: 重写字段类型
    9. 
  
    
    
  
  9.  * required: 字段是否必填
    10. 
  
    
    
  
  10.  * example: 举例说明
    11. 
  
    
    
  
  11.  * hidden: 是否隐藏显示
    12. 
  
    
    
  
  12.  */
    13. 
  
    
    
  
  13.  @ApiModelProperty(value = "id", example = "1", required = true)
    14. 
  
    
    
  
  14.  private Long id; //文章ID
    15. 
  
    
    
  
  15.  @ApiModelProperty(name = "name", value = "文章名称", example = "Swagger", required = true)
    16. 
  
    
    
  
  16.  private String name; //文章名称
    17. 
  
    
    
  
  17.  @ApiModelProperty(name = "title" ,value = "文章标题", example = "SpringBoot中使用Swagger", required = true)
    18. 
  
    
    
  
  18.  private String title; //文章标题
    19. 
  
    
    
  
  19.  @ApiModelProperty(name = "createTime", value = "创建时间", required = false)
    20. 
  
    
    
  
  20.  private Date createTime; //创建时间 
    21. 
  
    
    
  
  21. }
    22.

查看配置效果

（八）Spring Boot整合Swagger2

如上图所示，我在图中标记了Swagger注解对应的配置效果

解释

在控制器类

  • @Api: 标记在控制器类上

    • value: 控制器类名称

    • tags: 控制器类标签

  • @ApiOperation: 标记在映射方法上

    • value: 接口说明，展示在接口列表

    • notes：接口详细说明，展示在接口的详情页。

    • tags：接口的标签，相同标签的接口会在一个标签页下展示。

    • httpMethod：支持的HTTP的方法。

  • @ApiImplicitParam: 请求参数属性配置



    • name：参数名称

    • value：参数说明

    • required：是否必须

    • dataType：数据类型　　

注意 @ApiImplicitParams是 @ApiImplicitParam的容器，通过 @ApiImplicitParam可以配置请求参数个各自的属性，但是若请求参数是一个实体对象， @ApiImplicitParam也可以直接指向对象( dataType= @ApiModel的 value值)，然后在实体对象中对字段进行限定。


在实体类上

  • @ApiModel是对整个类的属性的配置：

    • value：类的说明

    • description：详细描述

  • @ApiModelProperty是对具体每个字段的属性配置：


    • name：字段名称

    • value：字段的说明

    • required：是否必须

    • example：示例值

    • hidden：是否显示




/ 往期推荐 /






END

     








以上是关于Spring Boot整合Swagger2的主要内容，如果未能解决你的问题，请参考以下文章

Spring Boot整合Swagger2构建RESTful API

Spring Boot 整合 swagger2 自动生成 RESTFul API 文档

Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

搭建基础后台框架及整合Swagger2及整合mybatisPlus代码器

SpringBoot之整合Swagger2