SpringBoot整合Swagger-ui快速生成在线API文档

天乔巴夏丶 2020-11-08 12:06:25
SpringBoot swagger ui 整合 swagger-ui


SpringBoot整合Swagger-ui实现在线API文档

Swagger是一款功能强大的api框架,支持在线接口文档的ui界面,还提供了在线测试功能,此外,它还支持流行的Restful风格接口。

本篇要点

  • 简单介绍restful风格。

  • 介绍SpringBoot与Swagger-ui快速整合。

  • 介绍Swagger-ui常用注解。

一、restful风格简单介绍

REST(Representational State Transfer):表述性状态传递,它是一种针对网络应用的设计和开发方式,可以降低开发的复杂性,提高系统的可伸缩性。

简单来说,HTTP协议本身是无状态的协议,客户端想要操作服务器,可以通过请求资源的方式,将"状态"进行传递。

  • GET请求表示获取资源。
  • POST请求表示新建资源。
  • PUT请求表示更新资源。
  • DELETE请求表示删除资源。

二、SpringBoot与Swagger-ui快速整合

1、第一种方式:使用官方依赖

一、导入依赖

 <properties>
<swagger.version>2.9.2</swagger.version>
</properties>
<!--swagger2官方依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>

二、编写Swagger的配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.pathMapping("/")
.select()
//为当前包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.hyh.fireworks.web"))
// 为有@Api注解的Controller生成API文档
//.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
// 为有@ApiOperation注解的方法生成API文档
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger接口文档")
.description("Fireworks 博客网站 接口文档 ")
.contact(new Contact("天乔巴夏", "https://www.hyhwky.com", "1332790762@qq.com"))
.version("1.0")
.build();
}
}

三、在实体类model上应用注解

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "User对象", description = "用户表")
public class User implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String name;
@ApiModelProperty(value = "年龄")
private Integer age;
}

四、在接口上应用注解

注:以下注解不加也是可以测试成功的,不过为了文档的可读性,建议加上方法注释。

@Api(tags = "User控制器") //修饰整个类,描述Controller的作用
@RestController
@RequestMapping("/users")
public class UserController {
private static final List<User> USERS = new ArrayList<>();
static {
USERS.add(new User(1,"hyh",12));
USERS.add(new User(2,"summer day",18));
USERS.add(new User(3,"天乔巴夏",20));
}
@GetMapping("/{id}")
@ApiOperation("获取指定user")
public User getUser(@PathVariable @ApiParam(value = "id",required = true,defaultValue = "3") Integer id){
return USERS.get(id - 1);
}
@DeleteMapping("/{id}")
@ApiOperation("删除指定user")
@ApiImplicitParam(name = "id", value = "user id", required = true, dataType = "Integer",paramType = "path")
public String deleteUser(@PathVariable Integer id){
USERS.remove(id - 1);
return "success";
}
@PostMapping()
@ApiOperation("新增用户")
public String postUser(@RequestBody User user){
USERS.add(user);
return "success";
}
@PutMapping("/{id}")
@ApiOperation("更新用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Integer",paramType = "path"),
@ApiImplicitParam(name = "user", value = "user 实体", required = true, dataType = "User")
})
public String putUser(@PathVariable Integer id , @RequestBody User user){
user.setId(id);
USERS.set(id - 1,user);
return "success";
}
@GetMapping()
@ApiOperation("用户列表")
public List<User> getUsers(){
return USERS;
}
@ApiIgnore //生成接口文档时,忽略该接口
@GetMapping("/ignore")
public String ignoreTest(){
return "ignore";
}
}

五、访问http://localhost:8081/swagger-ui.html即可看到效果

2、第二种方式:使用第三方依赖

文档及源码地址:https://github.com/SpringForAll/spring-boot-starter-swagger,内有详细文档说明,利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档,简化原生使用swagger2的整合代码。

感兴趣的小伙伴可以照着文档上的demo自己测试一下哈。

三、swagger-ui的基本注解

  • @Api:用于修饰Controller
  • @ApiOperation:用于修饰Controller类中的方法
  • @ApiParam:用于修饰接口中的参数
  • @ApiModelProperty:用于修饰实体类的属性

源码下载

本文内容均为对优秀博客及官方文档总结而得,原文地址均已在文中参考阅读处标注。最后,文中的代码样例已经全部上传至Gitee:https://gitee.com/tqbx/springboot-samples-learn,另有其他SpringBoot的整合哦。

参考阅读

版权声明
本文为[天乔巴夏丶]所创,转载请带上原文链接,感谢
https://www.cnblogs.com/summerday152/p/13943808.html

  1. 【计算机网络 12(1),尚学堂马士兵Java视频教程
  2. 【程序猿历程,史上最全的Java面试题集锦在这里
  3. 【程序猿历程(1),Javaweb视频教程百度云
  4. Notes on MySQL 45 lectures (1-7)
  5. [computer network 12 (1), Shang Xuetang Ma soldier java video tutorial
  6. The most complete collection of Java interview questions in history is here
  7. [process of program ape (1), JavaWeb video tutorial, baidu cloud
  8. Notes on MySQL 45 lectures (1-7)
  9. 精进 Spring Boot 03:Spring Boot 的配置文件和配置管理,以及用三种方式读取配置文件
  10. Refined spring boot 03: spring boot configuration files and configuration management, and reading configuration files in three ways
  11. 精进 Spring Boot 03:Spring Boot 的配置文件和配置管理,以及用三种方式读取配置文件
  12. Refined spring boot 03: spring boot configuration files and configuration management, and reading configuration files in three ways
  13. 【递归,Java传智播客笔记
  14. [recursion, Java intelligence podcast notes
  15. [adhere to painting for 386 days] the beginning of spring of 24 solar terms
  16. K8S系列第八篇(Service、EndPoints以及高可用kubeadm部署)
  17. K8s Series Part 8 (service, endpoints and high availability kubeadm deployment)
  18. 【重识 HTML (3),350道Java面试真题分享
  19. 【重识 HTML (2),Java并发编程必会的多线程你竟然还不会
  20. 【重识 HTML (1),二本Java小菜鸟4面字节跳动被秒成渣渣
  21. [re recognize HTML (3) and share 350 real Java interview questions
  22. [re recognize HTML (2). Multithreading is a must for Java Concurrent Programming. How dare you not
  23. [re recognize HTML (1), two Java rookies' 4-sided bytes beat and become slag in seconds
  24. 造轮子系列之RPC 1:如何从零开始开发RPC框架
  25. RPC 1: how to develop RPC framework from scratch
  26. 造轮子系列之RPC 1:如何从零开始开发RPC框架
  27. RPC 1: how to develop RPC framework from scratch
  28. 一次性捋清楚吧,对乱糟糟的,Spring事务扩展机制
  29. 一文彻底弄懂如何选择抽象类还是接口,连续四年百度Java岗必问面试题
  30. Redis常用命令
  31. 一双拖鞋引发的血案,狂神说Java系列笔记
  32. 一、mysql基础安装
  33. 一位程序员的独白:尽管我一生坎坷,Java框架面试基础
  34. Clear it all at once. For the messy, spring transaction extension mechanism
  35. A thorough understanding of how to choose abstract classes or interfaces, baidu Java post must ask interview questions for four consecutive years
  36. Redis common commands
  37. A pair of slippers triggered the murder, crazy God said java series notes
  38. 1、 MySQL basic installation
  39. Monologue of a programmer: despite my ups and downs in my life, Java framework is the foundation of interview
  40. 【大厂面试】三面三问Spring循环依赖,请一定要把这篇看完(建议收藏)
  41. 一线互联网企业中,springboot入门项目
  42. 一篇文带你入门SSM框架Spring开发,帮你快速拿Offer
  43. 【面试资料】Java全集、微服务、大数据、数据结构与算法、机器学习知识最全总结,283页pdf
  44. 【leetcode刷题】24.数组中重复的数字——Java版
  45. 【leetcode刷题】23.对称二叉树——Java版
  46. 【leetcode刷题】22.二叉树的中序遍历——Java版
  47. 【leetcode刷题】21.三数之和——Java版
  48. 【leetcode刷题】20.最长回文子串——Java版
  49. 【leetcode刷题】19.回文链表——Java版
  50. 【leetcode刷题】18.反转链表——Java版
  51. 【leetcode刷题】17.相交链表——Java&python版
  52. 【leetcode刷题】16.环形链表——Java版
  53. 【leetcode刷题】15.汉明距离——Java版
  54. 【leetcode刷题】14.找到所有数组中消失的数字——Java版
  55. 【leetcode刷题】13.比特位计数——Java版
  56. oracle控制用户权限命令
  57. 三年Java开发,继阿里,鲁班二期Java架构师
  58. Oracle必须要启动的服务
  59. 万字长文!深入剖析HashMap,Java基础笔试题大全带答案
  60. 一问Kafka就心慌?我却凭着这份,图灵学院vip课程百度云