SprintBoot 集成 swagger2 自动生成接口文档

本贴最后更新于 2250 天前,其中的信息可能已经物是人非

相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。

手写Api文档的几个痛点:

  1. 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
  2. 接口返回结果不明确
  3. 不能直接在线测试接口,通常需要使用工具,比如postman
  4. 接口文档太多,不好管理

Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。

其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式。

一、依赖

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

二、Swagger配置类

其实这个配置类,只要了解具体能配置哪些东西就好了,毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径,不然生成的文档扫描不到接口。

  1. package cn.saytime;
  2. import org.springframework.context.annotation.Bean;
  3. import org.springframework.context.annotation.Configuration;
  4. import springfox.documentation.builders.ApiInfoBuilder;
  5. import springfox.documentation.builders.PathSelectors;
  6. import springfox.documentation.builders.RequestHandlerSelectors;
  7. import springfox.documentation.service.ApiInfo;
  8. import springfox.documentation.spi.DocumentationType;
  9. import springfox.documentation.spring.web.plugins.Docket;
  10. /**
  11. * @author zh
  12. * @ClassName cn.saytime.Swgger2
  13. * @Description
  14. * @date 2017-07-10 22:12:31
  15. */
  16. @Configuration
  17. public class Swagger2 {
  18. @Bean
  19. public Docket createRestApi() {
  20. return new Docket(DocumentationType.SWAGGER_2)
  21. .apiInfo(apiInfo())
  22. .select()
  23. .apis(RequestHandlerSelectors.basePackage("cn.saytime.web"))
  24. .paths(PathSelectors.any())
  25. .build();
  26. }
  27. private ApiInfo apiInfo() {
  28. return new ApiInfoBuilder()
  29. .title("springboot利用swagger构建api文档")
  30. .description("简单优雅的restfun风格,http://blog.csdn.net/saytime")
  31. .termsOfServiceUrl("http://blog.csdn.net/saytime")
  32. .version("1.0")
  33. .build();
  34. }
  35. }

用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

  1. package cn.saytime;
  2. import org.springframework.boot.SpringApplication;
  3. import org.springframework.boot.autoconfigure.SpringBootApplication;
  4. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  5. @SpringBootApplication
  6. @EnableSwagger2
  7. public class SpringbootSwagger2Application {
  8. public static void main(String[] args) {
  9. SpringApplication.run(SpringbootSwagger2Application.class, args);
  10. }
  11. }

三、Restful 接口

  1. package cn.saytime.web;
  2. import cn.saytime.bean.JsonResult;
  3. import cn.saytime.bean.User;
  4. import io.swagger.annotations.Api;
  5. import io.swagger.annotations.ApiImplicitParam;
  6. import io.swagger.annotations.ApiImplicitParams;
  7. import io.swagger.annotations.ApiOperation;
  8. import org.springframework.http.ResponseEntity;
  9. import org.springframework.web.bind.annotation.PathVariable;
  10. import org.springframework.web.bind.annotation.RequestBody;
  11. import org.springframework.web.bind.annotation.RequestMapping;
  12. import org.springframework.web.bind.annotation.RequestMethod;
  13. import org.springframework.web.bind.annotation.RestController;
  14. import springfox.documentation.annotations.ApiIgnore;
  15. import java.util.ArrayList;
  16. import java.util.Collections;
  17. import java.util.HashMap;
  18. import java.util.List;
  19. import java.util.Map;
  20. /**
  21. * @author zh
  22. * @ClassName cn.saytime.web.UserController
  23. * @Description
  24. */
  25. @RestController
  26. public class UserController {
  27. // 创建线程安全的Map
  28. static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
  29. /**
  30. * 根据ID查询用户
  31. * @param id
  32. * @return
  33. */
  34. @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
  35. @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
  36. @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
  37. public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
  38. JsonResult r = new JsonResult();
  39. try {
  40. User user = users.get(id);
  41. r.setResult(user);
  42. r.setStatus("ok");
  43. } catch (Exception e) {
  44. r.setResult(e.getClass().getName() + ":" + e.getMessage());
  45. r.setStatus("error");
  46. e.printStackTrace();
  47. }
  48. return ResponseEntity.ok(r);
  49. }
  50. /**
  51. * 查询用户列表
  52. * @return
  53. */
  54. @ApiOperation(value="获取用户列表", notes="获取用户列表")
  55. @RequestMapping(value = "users", method = RequestMethod.GET)
  56. public ResponseEntity<JsonResult> getUserList (){
  57. JsonResult r = new JsonResult();
  58. try {
  59. List<User> userList = new ArrayList<User>(users.values());
  60. r.setResult(userList);
  61. r.setStatus("ok");
  62. } catch (Exception e) {
  63. r.setResult(e.getClass().getName() + ":" + e.getMessage());
  64. r.setStatus("error");
  65. e.printStackTrace();
  66. }
  67. return ResponseEntity.ok(r);
  68. }
  69. /**
  70. * 添加用户
  71. * @param user
  72. * @return
  73. */
  74. @ApiOperation(value="创建用户", notes="根据User对象创建用户")
  75. @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  76. @RequestMapping(value = "user", method = RequestMethod.POST)
  77. public ResponseEntity<JsonResult> add (@RequestBody User user){
  78. JsonResult r = new JsonResult();
  79. try {
  80. users.put(user.getId(), user);
  81. r.setResult(user.getId());
  82. r.setStatus("ok");
  83. } catch (Exception e) {
  84. r.setResult(e.getClass().getName() + ":" + e.getMessage());
  85. r.setStatus("error");
  86. e.printStackTrace();
  87. }
  88. return ResponseEntity.ok(r);
  89. }
  90. /**
  91. * 根据id删除用户
  92. * @param id
  93. * @return
  94. */
  95. @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
  96. @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
  97. @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
  98. public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
  99. JsonResult r = new JsonResult();
  100. try {
  101. users.remove(id);
  102. r.setResult(id);
  103. r.setStatus("ok");
  104. } catch (Exception e) {
  105. r.setResult(e.getClass().getName() + ":" + e.getMessage());
  106. r.setStatus("error");
  107. e.printStackTrace();
  108. }
  109. return ResponseEntity.ok(r);
  110. }
  111. /**
  112. * 根据id修改用户信息
  113. * @param user
  114. * @return
  115. */
  116. @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
  117. @ApiImplicitParams({
  118. @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
  119. @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
  120. })
  121. @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
  122. public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
  123. JsonResult r = new JsonResult();
  124. try {
  125. User u = users.get(id);
  126. u.setUsername(user.getUsername());
  127. u.setAge(user.getAge());
  128. users.put(id, u);
  129. r.setResult(u);
  130. r.setStatus("ok");
  131. } catch (Exception e) {
  132. r.setResult(e.getClass().getName() + ":" + e.getMessage());
  133. r.setStatus("error");
  134. e.printStackTrace();
  135. }
  136. return ResponseEntity.ok(r);
  137. }
  138. @ApiIgnore//使用该注解忽略这个API
  139. @RequestMapping(value = "/hi", method = RequestMethod.GET)
  140. public String jsonTest() {
  141. return " hi you!";
  142. }
  143. }

Json格式输出类 JsonResult.class

  1. package cn.saytime.bean;
  2. public class JsonResult {
  3. private String status = null;
  4. private Object result = null;
  5. // Getter Setter
  6. }

实体User.class

  1. package cn.saytime.bean;
  2. import java.util.Date;
  3. /**
  4. * @author zh
  5. * @ClassName cn.saytime.bean.User
  6. * @Description
  7. */
  8. public class User {
  9. private int id;
  10. private String username;
  11. private int age;
  12. private Date ctm;
  13. // Getter Setter
  14. }

项目结构:

这里写图片描述

四、Swagger2文档

启动SpringBoot项目,访问 http://localhost:8080/swagger-ui.html

这里写图片描述

具体里面的内容以及接口测试,应该一看就懂了。这里就不一一截图了。

五、将swagger-ui.html设为首页

1.static目录下新增index.html文件

2.将index页面设置跳转至swagger-ui.html页

  1. <script>
  2. window.location.href="swagger-ui.html"
  3. </script>

六、Swagger注解

swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息
  • @ApiImplicitParam:一个请求参数
  • @ApiImplicitParams:多个请求参数



  • Spring

    Spring 是一个开源框架,是于 2003 年兴起的一个轻量级的 Java 开发框架,由 Rod Johnson 在其著作《Expert One-On-One J2EE Development and Design》中阐述的部分理念和原型衍生而来。它是为了解决企业应用开发的复杂性而创建的。框架的主要优势之一就是其分层架构,分层架构允许使用者选择使用哪一个组件,同时为 JavaEE 应用程序开发提供集成的框架。

    942 引用 • 1459 回帖 • 58 关注
  • Swagger

    Swagger 是一款非常流行的 API 开发工具,它遵循 OpenAPI Specification(这是一种通用的、和编程语言无关的 API 描述规范)。Swagger 贯穿整个 API 生命周期,如 API 的设计、编写文档、测试和部署。

    26 引用 • 35 回帖
  • Maven

    Maven 是基于项目对象模型(POM)、通过一小段描述信息来管理项目的构建、报告和文档的软件项目管理工具。

    186 引用 • 318 回帖 • 319 关注

相关帖子

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...

推荐标签 标签

  • 面试

    面试造航母,上班拧螺丝。多面试,少加班。

    325 引用 • 1395 回帖 • 1 关注
  • Bug

    Bug 本意是指臭虫、缺陷、损坏、犯贫、窃听器、小虫等。现在人们把在程序中一些缺陷或问题统称为 bug(漏洞)。

    75 引用 • 1737 回帖 • 2 关注
  • gRpc
    11 引用 • 9 回帖 • 55 关注
  • IDEA

    IDEA 全称 IntelliJ IDEA,是一款 Java 语言开发的集成环境,在业界被公认为最好的 Java 开发工具之一。IDEA 是 JetBrains 公司的产品,这家公司总部位于捷克共和国的首都布拉格,开发人员以严谨著称的东欧程序员为主。

    180 引用 • 400 回帖 • 2 关注
  • 尊园地产

    昆明尊园房地产经纪有限公司,即:Kunming Zunyuan Property Agency Company Limited(简称“尊园地产”)于 2007 年 6 月开始筹备,2007 年 8 月 18 日正式成立,注册资本 200 万元,公司性质为股份经纪有限公司,主营业务为:代租、代售、代办产权过户、办理银行按揭、担保、抵押、评估等。

    1 引用 • 22 回帖 • 732 关注
  • Jenkins

    Jenkins 是一套开源的持续集成工具。它提供了非常丰富的插件,让构建、部署、自动化集成项目变得简单易用。

    52 引用 • 37 回帖
  • BAE

    百度应用引擎(Baidu App Engine)提供了 PHP、Java、Python 的执行环境,以及云存储、消息服务、云数据库等全面的云服务。它可以让开发者实现自动地部署和管理应用,并且提供动态扩容和负载均衡的运行环境,让开发者不用考虑高成本的运维工作,只需专注于业务逻辑,大大降低了开发者学习和迁移的成本。

    19 引用 • 75 回帖 • 622 关注
  • Openfire

    Openfire 是开源的、基于可拓展通讯和表示协议 (XMPP)、采用 Java 编程语言开发的实时协作服务器。Openfire 的效率很高,单台服务器可支持上万并发用户。

    6 引用 • 7 回帖 • 95 关注
  • 域名

    域名(Domain Name),简称域名、网域,是由一串用点分隔的名字组成的 Internet 上某一台计算机或计算机组的名称,用于在数据传输时标识计算机的电子方位(有时也指地理位置)。

    43 引用 • 208 回帖
  • Eclipse

    Eclipse 是一个开放源代码的、基于 Java 的可扩展开发平台。就其本身而言,它只是一个框架和一组服务,用于通过插件组件构建开发环境。

    75 引用 • 258 回帖 • 630 关注
  • 游戏

    沉迷游戏伤身,强撸灰飞烟灭。

    176 引用 • 814 回帖 • 1 关注
  • SOHO

    为成为自由职业者在家办公而努力吧!

    7 引用 • 55 回帖 • 31 关注
  • 电影

    这是一个不能说的秘密。

    120 引用 • 599 回帖
  • Vditor

    Vditor 是一款浏览器端的 Markdown 编辑器,支持所见即所得、即时渲染(类似 Typora)和分屏预览模式。它使用 TypeScript 实现,支持原生 JavaScript、Vue、React 和 Angular。

    345 引用 • 1778 回帖
  • 创造

    你创造的作品可能会帮助到很多人,如果是开源项目的话就更赞了!

    175 引用 • 994 回帖 • 3 关注
  • 锤子科技

    锤子科技(Smartisan)成立于 2012 年 5 月,是一家制造移动互联网终端设备的公司,公司的使命是用完美主义的工匠精神,打造用户体验一流的数码消费类产品(智能手机为主),改善人们的生活质量。

    4 引用 • 31 回帖 • 1 关注
  • Firefox

    Mozilla Firefox 中文俗称“火狐”(正式缩写为 Fx 或 fx,非正式缩写为 FF),是一个开源的网页浏览器,使用 Gecko 排版引擎,支持多种操作系统,如 Windows、OSX 及 Linux 等。

    8 引用 • 30 回帖 • 415 关注
  • 导航

    各种网址链接、内容导航。

    38 引用 • 169 回帖
  • 安装

    你若安好,便是晴天。

    131 引用 • 1184 回帖 • 2 关注
  • 星云链

    星云链是一个开源公链,业内简单的将其称为区块链上的谷歌。其实它不仅仅是区块链搜索引擎,一个公链的所有功能,它基本都有,比如你可以用它来开发部署你的去中心化的 APP,你可以在上面编写智能合约,发送交易等等。3 分钟快速接入星云链 (NAS) 测试网

    3 引用 • 16 回帖
  • Java

    Java 是一种可以撰写跨平台应用软件的面向对象的程序设计语言,是由 Sun Microsystems 公司于 1995 年 5 月推出的。Java 技术具有卓越的通用性、高效性、平台移植性和安全性。

    3170 引用 • 8209 回帖 • 2 关注
  • Wide

    Wide 是一款基于 Web 的 Go 语言 IDE。通过浏览器就可以进行 Go 开发,并有代码自动完成、查看表达式、编译反馈、Lint、实时结果输出等功能。

    欢迎访问我们运维的实例: https://wide.b3log.org

    30 引用 • 218 回帖 • 615 关注
  • CongSec

    本标签主要用于分享网络空间安全专业的学习笔记

    1 引用 • 1 回帖 • 2 关注
  • 架构

    我们平时所说的“架构”主要是指软件架构,这是有关软件整体结构与组件的抽象描述,用于指导软件系统各个方面的设计。另外还有“业务架构”、“网络架构”、“硬件架构”等细分领域。

    142 引用 • 442 回帖
  • 数据库

    据说 99% 的性能瓶颈都在数据库。

    336 引用 • 669 回帖 • 1 关注
  • 博客

    记录并分享人生的经历。

    272 引用 • 2386 回帖
  • Ruby

    Ruby 是一种开源的面向对象程序设计的服务器端脚本语言,在 20 世纪 90 年代中期由日本的松本行弘(まつもとゆきひろ/Yukihiro Matsumoto)设计并开发。在 Ruby 社区,松本也被称为马茨(Matz)。

    7 引用 • 31 回帖 • 204 关注