springboot整合swagger
1.背景
前后端分离后，维护接口文档基本上是必不可少的工作。
一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。
但问题是,现在都是所谓的"敏捷开发",也就是说接口随时要变,这样一来,维护接口文档就成了必不可少的工作了...
别小看维护接口这个工作,做了开发的都明白....虽然不难但是很麻烦的...而且经常维护不及时...
幸好有"丝袜哥"swagger,只需要简单的配置就可以生成接口文档....下面我们隆重的请丝袜哥闪亮登场.....
2.步骤
备注:这里是讲在原来的springboot项目中配置swagger
步骤一:引入jar包
<!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
步骤二:WebMvcConfigurer,中排除对swagger的拦截(如果项目中没有拦截器可以不用)
@Bean public FilterRegistrationBean filterRegist() { FilterRegistrationBean frBean = new FilterRegistrationBean(); frBean.setFilter(new HttpServletRequestWrapperFilter()); frBean.addUrlPatterns("/*"); frBean.addInitParameter("exclusions", "/api/swagger-resources/**,/api/webjars/**,/api/v2/**,/api/swagger-ui.html/**"); return frBean; }
步骤三:启动项目然后访问swagger地址:http://localhost:8080/api/swagger-ui.html
界面如下:
到这里swagger的整合已经完成,
当然这是一个最简单的整合,所有的都是swagger的默认配置,其实swagger还有很多其他的配置,但是我们觉得都是一些华而不实的,几乎用处不大
因为swagger生成的接口文档一般是公司内部使用的,只要能详细知道接口信息就可以了
3.在controller层给接口进行描述
先把controller的代码放上,其他的在详解
package com.ldp.user.controller; import com.ldp.user.common.annatation.ApiToken; import com.ldp.user.common.base.BaseResponse; import com.ldp.user.common.base.ResponseBuilder; import com.ldp.user.entity.dto.UserSwaggerDTO; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; /** * @author 姿势帝-博客园 * @address https://www.cnblogs.com/newAndHui/ * @WeChat 851298348 * @create 01/03 5:59 * @description <P> * swagger用法展示与测试用 * </P> */ @RestController @RequestMapping("/test") @Api(tags = "丝袜哥演示接口") // 接口名称,默认为当前类名 TestSwaggerController public class TestSwaggerController { /** * 演示swagger参数没有封装的写法 * * @param username * @param weChat * @param address * @return */ @ApiToken(required = false) @PostMapping("/addUser") // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写, // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....) @ApiOperation(value = "添加用户的接口(不封装参数)", notes = "演示swagger参数没有封装的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用") // 接口参数描述(选填) @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "张无忌", required = true), @ApiImplicitParam(name = "weChat", value = "微信", defaultValue = "851298348"), @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "光明顶") }) public BaseResponse addUser(@RequestParam(required = true) String username, String weChat, String address) { System.out.println("username=" + username); System.out.println("weChat=" + weChat); System.out.println("address=" + address); return ResponseBuilder.success("丝袜哥演示成功"); } /** * 演示swagger参数 封装后的写法 * * @param dto * @return */ @ApiToken(required = false) @PostMapping("/addUser2") // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写, // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....) @ApiOperation(value = "添加用户的接口2(参数使用对象封装)", notes = "演示swagger参数封装后的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用") public BaseResponse addUser2(UserSwaggerDTO dto) { System.out.println("2 username=" + dto.getUserName()); System.out.println("2 weChat=" + dto.getWeChat()); System.out.println("2 address=" + dto.getAddress()); return ResponseBuilder.success("丝袜哥演示成功2"); } }
方式一:参数没有封装的写法
/** * 演示swagger参数没有封装的写法 * * @param username * @param weChat * @param address * @return */ @ApiToken(required = false) @PostMapping("/addUser") // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写, // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....) @ApiOperation(value = "添加用户的接口", notes = "演示swagger参数没有封装的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用") // 接口参数描述(选填) @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "张无忌", required = true), @ApiImplicitParam(name = "weChat", value = "微信", defaultValue = "851298348"), @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "光明顶") }) public BaseResponse addUser(@RequestParam(required = true) String username, String weChat, String address) { System.out.println("username=" + username); System.out.println("weChat=" + weChat); System.out.println("address=" + address); return ResponseBuilder.success("丝袜哥演示成功"); }
方式二:参数封装成对象的写法
controller接口方法
/** * 演示swagger参数 封装后的写法 * * @param dto * @return */ @ApiToken(required = false) @PostMapping("/addUser2") // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写, // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....) @ApiOperation(value = "添加用户的接口2", notes = "演示swagger参数封装后的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用") public BaseResponse addUser2(UserSwaggerDTO dto) { System.out.println("2 username=" + dto.getUserName()); System.out.println("2 weChat=" + dto.getWeChat()); System.out.println("2 address=" + dto.getAddress()); return ResponseBuilder.success("丝袜哥演示成功2"); }
接口参数对象
package com.ldp.user.entity.dto; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; /** * @author 姿势帝-博客园 * @address https://www.cnblogs.com/newAndHui/ * @WeChat 851298348 * @create 01/03 6:19 * @description */ @Data @ApiModel("新增用户参数对象") public class UserSwaggerDTO { @ApiModelProperty(value = "用户名", example = "赵敏", required = true) private String userName; @ApiModelProperty(value = "微信", example = "851298348") private String weChat; @ApiModelProperty(value = "地址", example = "峨眉山") private String address; }
以上两种方式在页面上的结果
打开看接口详情
进入测试
测试结果
其实swagger还有很多华而不实的功能,如果大家感兴趣可以自己去研究,
我在这里只是站在生产的角度讲解常用的功能
如果常用的功能还没有理解到可以看视频演示或者单独问我额!
