springboot整合swagger

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的。

Swagger的maven依赖

<!-- swagger2支持 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>

Swagger配置文件

package com.fc.test.system.config; import com.fc.test.common.constant.ConstantConfig; 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.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * [简要描述]: 基于swagger2的配置<br/> * [详细描述]: * * @author zzc * @time 2018/9/3 * @since v0.8 */ @Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket createRestfulApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) //是否开启 true false .enable(ConstantConfig.swaggerEnable) .select() //控制层包目录 .apis(RequestHandlerSelectors.basePackage("com.fc.test.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("系统文档-PDMS") .description("powered By zhouzaichun") .termsOfServiceUrl("") //.contact(contact) .version("1.0") .build(); } }

控制层

package com.fc.test.controller.user; import com.fc.test.common.RespStatus; import com.fc.test.common.RestResponse; import com.fc.test.model.TSysUser; import com.fc.test.service.TSysUserService; import com.github.pagehelper.PageInfo; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; import javax.annotation.Resource; import lombok.extern.slf4j.Slf4j; import org.apache.shiro.authz.annotation.Logical; import org.apache.shiro.authz.annotation.RequiresPermissions; import org.apache.shiro.authz.annotation.RequiresRoles; import org.springframework.web.bind.annotation.*; /** * [简要描述]:Restful控制器 <br/> * [详细描述]: * * @author zzc * @time 2019/10/25 * @since V0.1 */ @Slf4j @Api(value = "用户管理", tags = {"用户管理"}) @RestController @RequestMapping("/api/v1/t/sys/user") public class TSysUserController { @Resource private TSysUserService tSysUserService; @ApiOperation(value = "数据新增") @ApiResponses({ @ApiResponse(code = 200, message = "成功", response = String.class), @ApiResponse(code = 101, message = "数据校验未通过"), @ApiResponse(code = 999, message = "失败"), @ApiResponse(code = 1501, message = "用户令牌过期"), }) @PostMapping public RestResponse add(@RequestBody TSysUser tSysUser) { String id = tSysUserService.saveTSysUser(tSysUser); return RestResponse.builder().respStatus(RespStatus.SUCCESS).respData(id).build(); } @RequiresRoles(value = { "admin"},logical = Logical.OR) @ApiOperation(value = "数据删除") @ApiResponses({ @ApiResponse(code = 200, message = "成功", response = String.class), @ApiResponse(code = 101, message = "数据校验未通过"), @ApiResponse(code = 999, message = "失败"), @ApiResponse(code = 1501, message = "用户令牌过期"), }) @DeleteMapping("/{id}") public RestResponse delete(@ApiParam(value = "数据id") @PathVariable String id) { tSysUserService.deleteTSysUserById(id); return RestResponse.ok(); } @ApiOperation(value = "数据修改") @ApiResponses({ @ApiResponse(code = 200, message = "成功", response = String.class), @ApiResponse(code = 101, message = "数据校验未通过"), @ApiResponse(code = 999, message = "失败"), @ApiResponse(code = 1501, message = "用户令牌过期"), }) @PutMapping public RestResponse update(@RequestBody TSysUser tSysUser) { tSysUserService.updateTSysUser(tSysUser); return RestResponse.ok(); } @ApiOperation(value = "获取数据详情") @ApiResponses({ @ApiResponse(code = 200, message = "成功", response = TSysUser.class), @ApiResponse(code = 101, message = "数据校验未通过"), @ApiResponse(code = 999, message = "失败"), @ApiResponse(code = 1501, message = "用户令牌过期"), }) @GetMapping("/{id}") public RestResponse detail(@ApiParam(value = "数据id") @PathVariable String id) { TSysUser tSysUser = tSysUserService.findTSysUserById(id); return RestResponse.builder().respStatus(RespStatus.SUCCESS).respData(tSysUser).build(); } @ApiOperation(value = "获取数据列表") @ApiResponses({ @ApiResponse(code = 200, message = "成功", response = TSysUser.class), @ApiResponse(code = 101, message = "数据校验未通过"), @ApiResponse(code = 999, message = "失败"), @ApiResponse(code = 1501, message = "用户令牌过期"), }) @ApiImplicitParams({ @ApiImplicitParam(name = "page", value = "页数 "), @ApiImplicitParam(name = "size", value = "每页数量 "), }) @GetMapping public RestResponse list(@RequestParam(defaultValue = "1") Integer page, @RequestParam(defaultValue = "10") Integer size) { PageInfo pageInfo = tSysUserService.findTSysUserList(page, size); return RestResponse.builder().respStatus(RespStatus.SUCCESS).respData(pageInfo).build(); } }

实体类

package com.fc.test.model; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.persistence.*; @Data @ApiModel(description = "用户实体") @Table(name = "t_sys_user") public class TSysUser { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private String id; /** * 用户账号 */ @ApiModelProperty(value="用户账号",example="admin") private String username; /** * 用户密码 */ @ApiModelProperty(value="密码",example="123456") private String password; }

过滤器放行

访问