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

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

相信各位在公司写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 应用程序开发提供集成的框架。

    943 引用 • 1460 回帖 • 3 关注
  • Swagger

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

    26 引用 • 35 回帖 • 5 关注
  • Maven

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

    186 引用 • 318 回帖 • 282 关注

相关帖子

欢迎来到这里!

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

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

推荐标签 标签

  • DNSPod

    DNSPod 建立于 2006 年 3 月份,是一款免费智能 DNS 产品。 DNSPod 可以为同时有电信、网通、教育网服务器的网站提供智能的解析,让电信用户访问电信的服务器,网通的用户访问网通的服务器,教育网的用户访问教育网的服务器,达到互联互通的效果。

    6 引用 • 26 回帖 • 517 关注
  • 单点登录

    单点登录(Single Sign On)是目前比较流行的企业业务整合的解决方案之一。SSO 的定义是在多个应用系统中,用户只需要登录一次就可以访问所有相互信任的应用系统。

    9 引用 • 25 回帖
  • 生活

    生活是指人类生存过程中的各项活动的总和,范畴较广,一般指为幸福的意义而存在。生活实际上是对人生的一种诠释。生活包括人类在社会中与自己息息相关的日常活动和心理影射。

    230 引用 • 1454 回帖
  • Rust

    Rust 是一门赋予每个人构建可靠且高效软件能力的语言。Rust 由 Mozilla 开发,最早发布于 2014 年 9 月。

    58 引用 • 22 回帖
  • C++

    C++ 是在 C 语言的基础上开发的一种通用编程语言,应用广泛。C++ 支持多种编程范式,面向对象编程、泛型编程和过程化编程。

    107 引用 • 153 回帖
  • 智能合约

    智能合约(Smart contract)是一种旨在以信息化方式传播、验证或执行合同的计算机协议。智能合约允许在没有第三方的情况下进行可信交易,这些交易可追踪且不可逆转。智能合约概念于 1994 年由 Nick Szabo 首次提出。

    1 引用 • 11 回帖 • 2 关注
  • 服务

    提供一个服务绝不仅仅是简单的把硬件和软件累加在一起,它包括了服务的可靠性、服务的标准化、以及对服务的监控、维护、技术支持等。

    41 引用 • 24 回帖
  • PWA

    PWA(Progressive Web App)是 Google 在 2015 年提出、2016 年 6 月开始推广的项目。它结合了一系列现代 Web 技术,在网页应用中实现和原生应用相近的用户体验。

    14 引用 • 69 回帖 • 159 关注
  • Kotlin

    Kotlin 是一种在 Java 虚拟机上运行的静态类型编程语言,由 JetBrains 设计开发并开源。Kotlin 可以编译成 Java 字节码,也可以编译成 JavaScript,方便在没有 JVM 的设备上运行。在 Google I/O 2017 中,Google 宣布 Kotlin 成为 Android 官方开发语言。

    19 引用 • 33 回帖 • 63 关注
  • 安装

    你若安好,便是晴天。

    132 引用 • 1184 回帖 • 1 关注
  • iOS

    iOS 是由苹果公司开发的移动操作系统,最早于 2007 年 1 月 9 日的 Macworld 大会上公布这个系统,最初是设计给 iPhone 使用的,后来陆续套用到 iPod touch、iPad 以及 Apple TV 等产品上。iOS 与苹果的 Mac OS X 操作系统一样,属于类 Unix 的商业操作系统。

    85 引用 • 139 回帖
  • 人工智能

    人工智能(Artificial Intelligence)是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门技术科学。

    135 引用 • 190 回帖
  • jQuery

    jQuery 是一套跨浏览器的 JavaScript 库,强化 HTML 与 JavaScript 之间的操作。由 John Resig 在 2006 年 1 月的 BarCamp NYC 上释出第一个版本。全球约有 28% 的网站使用 jQuery,是非常受欢迎的 JavaScript 库。

    63 引用 • 134 回帖 • 724 关注
  • Shell

    Shell 脚本与 Windows/Dos 下的批处理相似,也就是用各类命令预先放入到一个文件中,方便一次性执行的一个程序文件,主要是方便管理员进行设置或者管理用的。但是它比 Windows 下的批处理更强大,比用其他编程程序编辑的程序效率更高,因为它使用了 Linux/Unix 下的命令。

    123 引用 • 74 回帖 • 2 关注
  • LeetCode

    LeetCode(力扣)是一个全球极客挚爱的高质量技术成长平台,想要学习和提升专业能力从这里开始,充足技术干货等你来啃,轻松拿下 Dream Offer!

    209 引用 • 72 回帖
  • jsoup

    jsoup 是一款 Java 的 HTML 解析器,可直接解析某个 URL 地址、HTML 文本内容。它提供了一套非常省力的 API,可通过 DOM,CSS 以及类似于 jQuery 的操作方法来取出和操作数据。

    6 引用 • 1 回帖 • 484 关注
  • Notion

    Notion - The all-in-one workspace for your notes, tasks, wikis, and databases.

    7 引用 • 40 回帖
  • wolai

    我来 wolai:不仅仅是未来的云端笔记!

    2 引用 • 14 回帖 • 1 关注
  • QQ

    1999 年 2 月腾讯正式推出“腾讯 QQ”,在线用户由 1999 年的 2 人(马化腾和张志东)到现在已经发展到上亿用户了,在线人数超过一亿,是目前使用最广泛的聊天软件之一。

    45 引用 • 557 回帖 • 44 关注
  • 阿里巴巴

    阿里巴巴网络技术有限公司(简称:阿里巴巴集团)是以曾担任英语教师的马云为首的 18 人,于 1999 年在中国杭州创立,他们相信互联网能够创造公平的竞争环境,让小企业通过创新与科技扩展业务,并在参与国内或全球市场竞争时处于更有利的位置。

    43 引用 • 221 回帖 • 106 关注
  • TensorFlow

    TensorFlow 是一个采用数据流图(data flow graphs),用于数值计算的开源软件库。节点(Nodes)在图中表示数学操作,图中的线(edges)则表示在节点间相互联系的多维数据数组,即张量(tensor)。

    20 引用 • 19 回帖 • 1 关注
  • IDEA

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

    181 引用 • 400 回帖
  • OpenStack

    OpenStack 是一个云操作系统,通过数据中心可控制大型的计算、存储、网络等资源池。所有的管理通过前端界面管理员就可以完成,同样也可以通过 Web 接口让最终用户部署资源。

    10 引用 • 1 关注
  • 博客

    记录并分享人生的经历。

    273 引用 • 2388 回帖
  • Gzip

    gzip (GNU zip)是 GNU 自由软件的文件压缩程序。我们在 Linux 中经常会用到后缀为 .gz 的文件,它们就是 Gzip 格式的。现今已经成为互联网上使用非常普遍的一种数据压缩格式,或者说一种文件格式。

    9 引用 • 12 回帖 • 147 关注
  • RYMCU

    RYMCU 致力于打造一个即严谨又活泼、专业又不失有趣,为数百万人服务的开源嵌入式知识学习交流平台。

    4 引用 • 6 回帖 • 52 关注
  • 笔记

    好记性不如烂笔头。

    308 引用 • 793 回帖