Springboot整合swagger2

善良的小黑哥 2021-01-22 15:50:09
SpringBoot swagger swagger2 整合


前言

最近新入职了一家公司,项目开发完毕发现没有写接口的API文档工具,问了一下组长,组长告诉我说平常都是口头交流调试,用不着接口文档......想着能少费点口水,于是简单就整合一个swagger2,下面贴上代码。

Jar包依赖

我们用的是Maven项目,所以直接在pom.xml中进行依赖,因为我们项目使用的Springboot-1.3.5,所以依赖比较低,如果是高版本的小伙伴,可以自行下载对应的版本依赖。

附上maven仓库地址:https://mvnrepository.com/search?q=swagger2

 <!-- swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>

配置类

然后我们需要新建一个swagger配置类

package net.XXXX.xx.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import springfox.documentation.service.Parameter;
import springfox.documentation.builders.ParameterBuilder;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("net.XXX.xx"))//这里是自己的包结构
.paths(PathSelectors.any())
.build()
.globalOperationParameters(globalOperation());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口示例文档")
.description("接口文档Demo")
.version("1.0")
.build();
}
//下面代码可以酌情处理,因为我们接口需要有token验证,所以需要配置一下token输入框,下面代码就是做这个功能的
private List<Parameter> globalOperation(){
//添加head参数配置start
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
//第一个token为传参的key,第二个token为swagger页面显示的值
tokenPar.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
return pars;
}
} 

注意

如果大家项目中有过滤器,需要将swagger的访问地址释放掉,将以下地址进行释放。

swagger-resources/*
swagger-ui.html/*
v2/*
webjars/*

示例Controller

这里我们用一个GET请求做一下示例,标注一下Controller以及参数,请忽略代码内容~

@Api(value = "RevenueBudgetReisterController", description = "收入预算登记API")
@RestController
@RequestMapping("/revenueBudgetRegister")
public class RevenueBudgetReisterController extends BaseController {
private RevenueBudgetRegisterService registerService;
@Autowired
public RevenueBudgetReisterController(RevenueBudgetRegisterService registerService) {
this.registerService = registerService;
}
@ApiOperation(value = "获取一条记录", notes = "获取预算的明细记录")
@ApiImplicitParams({
@ApiImplicitParam(name = "year", value = "年份", required = true, dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "dictionaryName", value = "科目名称", required = false, dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "departmentId", value = "部门ID", required = true, dataType = "String", paramType = "query")
})
@RequestMapping(value = "/v1.0/revenueBudgetTetails", method = RequestMethod.GET)
public ResultDto revenueBudgetTetails(String year, String dictionaryName, String departmentId) {
if (null == year || year.equals("")
|| null == departmentId || "".equals(departmentId)) {
return new ResultDto(ResultDto.CODE_FAIL, RevenueBudgetDetailsController.ERROR_DATA, null);
}
List<RevenueBudgetDetailsVo> details = registerService.details(year, dictionaryName, departmentId);
return new ResultDto(ResultDto.CODE_SUCCESS, RevenueBudgetDetailsController.SUCCEEDED, details);
}
}

项目启动

访问地址:http://localhost:8006/swagger-ui.html#/     地址端口号大家请更改为与自己相对应的,我这里设置的是8006

bingo!~  出现这个界面就表示成功了!(  老汉激动摸了摸自己的秃头,从轮椅上站了起来,流下了开心的泪水.....)

然后我们随便点进去一个

这里会显示我们接口的入参,以及请求方式等信息,如果我们配置了token输入框,这里则会显示出来。

关于启动问题

可能集成swagger会出现下面这个异常。

集成swagger2报错:java.lang.NoSuchMethodError: com.google.common.XXX

出现这个异常是因为swagger中内置了一个谷歌的guava包,而项目中也有guava的依赖,版本不一致导致的冲突,我们需要将版本进行匹配,或者将低版本的依赖给排除掉,我这里降低了版本,本来项目中依赖的是swagger-2.9.2的版本,于是降低到了swagger-2.4.0版本,完美解决~

-

Swagger常用注解

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

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

本次教程就到这里了,谢谢大家阅读, 写的有不对的地方还请多多包涵以及提出!

版权声明
本文为[善良的小黑哥]所创,转载请带上原文链接,感谢
https://segmentfault.com/a/1190000039061952

  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课程百度云