玩转 SpringBoot 2 快速整合 | 丝袜哥(Swagger)
概述
首先让我引用 Swagger 官方的介绍:
Design is the foundation of your API development. Swagger makes API design a breeze, with easy-to-use tools for developers, architects, and product owners.
设计是API开发的基础。Swagger使API设计变得轻而易举,为开发人员,架构师和产品所有者提供了易于使用的工具。
作为一个后端开发者,你是否为开发完 API 接口后为写文档而烦恼、当 App 开发人员或前端开发人员看不懂的你写的接口文档,你还得去给他们讲一遍怎么使用而烦恼。
使用 Swagger 这些烦恼统统的消失,Swagger一个集预览和测试于一身的在线可视化 RESTful 风格的 Web 服务框架。
闲话少说,直接开整!
基础配置和 API 接口开发
第一步:先引入Swagger starter 依赖到 pom 文件中。我们这里采用2.7.0 版本
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
还有一点需要注意的是必须引入 Spring Boot Web starter 依赖。
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
第二步:编写 RESTful API 服务:一个用户的增删改查。
public class User { private String name; private Integer age; //......省略get and set方法 }
定义用户 RESTFull API 服务 Controller。
@RestController() @RequestMapping("/user") public class UserController { //...... }
在 RESTFull API 服务 Controller 添加根据 id查询用户的接口
/** * 根据用户id 查询用户 * @return */ @GetMapping("/{id}") public User get(@PathVariable(name = "id") Long id){ User user = new User(); user.setName("lijunkui"); user.setAge(18); log.info("springboot查询用户成功:"+"id:{}",id); return user; }
定义添加用户接口。
/** * 添加用户 */ @PostMapping() public void add(User user){ log.info("springboot添加用户成功:"+"name:{},age:{}",user.getName(),user.getAge()); }
定义更新用户接口。
/** * 全部更新 * @param user */ @PutMapping() public void updatePut(User user){ log.info("springboot Put 修改用户成功:"+"name:{},age:{}",user.getName(),user.getAge()); }
定义 局部更新用户接口。
/** * 局部更新 */ public void updatePatch(@PathVariable("name") String name){ log.info("springboot Patch 修改用户成功:"+"name:{}",name); }
定义删除用户接口。
/** * 删除用户 */ @DeleteMapping("/{id}") public void delete(@PathVariable("id") Long id){ User user = new User(); user.setName("lijunkui"); user.setAge(18); log.info("springboot 删除用户成功:"+"id:{}",id); }
定义根据 json 数据更新用户接口。
/** * 根据requestBody 更新用户信息 * @param user * @return */ @PostMapping("/updateUserByRequestBody") public void updateUserByRequestBody(@RequestBody User user){ log.info("updateUserByRequestBody 修改用户成功:"+"name:{},age:{}",user.getName(),user.getAge()); }
第三步:编写 Swagger 的Config配置类
//让Spring来加载该类配置 @Configuration //是否禁用swagger 的配置 @ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true") //启用Swagger2 @EnableSwagger2 public class SwaggerConfig { @Bean public Docket alipayApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("简单用户管理API接口文档") .apiInfo(apiInfo()) .select() //扫描配置 classpath 路径配置 Swagger注解下的 Api文档。 .apis(RequestHandlerSelectors.basePackage("com.ljk.springBootLearn.users")) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("SprignBoot学习专栏") .description("集成swagger") .termsOfServiceUrl("https://blog.csdn.net/ljk126wy") //创建人 .contact(new Contact("桌前明月", "http://www.baidu.com", "")) //版本 .version("1.0") //API 描述 .description("简单介绍如有问题还望指正")// .build(); } }
我来简单介绍一下 Swagger 的配置类中方法使用介绍。
每一组 Controller 的 Api 都对应一个 Docket 配置 ,如果有多个组 Api 就应该配置多个Docket 的 Bean。
Docket.groupName(String name):配置接口分组的名称,name为分组的名称。对应下图中红色框中的信息
apiInfo(ApiInfo apiInfo ) 配置Api 文档的一些公共的描述信息,对应下图中红色框中的信息。
paths():配置需要显示具体 Api 的路径。
我们通过PathSelectors类的4个方法来进行判断
- PathSelectors.any(): 所有的api都显示
- PathSelectors.none(): 所有的路径都不显示
- PathSelectors.regex(String pathRegex): 按照String的matches方法进行匹配。例如:PathSelectors.regex("/user/*")
- PathSelectors.ant(String antPattern): 按照Spring的AntPathMatcher提供的match方法进行匹配 例如:PathSelectors.ant("/user/**")
AntPathMatcher.match(String pattern, String path) 可以做URLs匹配,规则如下?匹配一个字符
*匹配0个或多个字符
** 匹配0个或多个目录
第四步:在application.properties 或 application.yml中添加配置信息。
在application.properties 配置信息如下:
server.port=8080 server.servlet.context-path=/sbe swagger.enable = true application.yml 配置内容如下:
application.yml 配置信息如下:
server: port: 8080 #游览器访问项目端口号 servlet: context-path:/sbe #游览器访问项目的名称 swagger: enable: true
需要注意的是application.properties 或 application.yml 只能存在一个,swagger.enable =
true表示是否使用Swagger的的功能。主要用于生产环境和开发环境的配置。切记生产环境要配置成false。
到目前为止SpringBoot 整合 Swagger 基础部分搭建完毕!接下来让我们今天的重点 Swagger 配置注解。
Swagger 注解使用实战
@Api : 说明接口类的作用。
@Api(tags ="用户管理") @RestController() @RequestMapping("/user") public class UserController { }
访问 Swagger UI 界面如下:
@ApiOperation: 用在方法上 说明方法的作用。
@ApiOperation(value="根据id获取用户信息") @GetMapping("/{id}") public User get(@PathVariable(name = "id") Long id){ //省略逻辑代码 }
访问 Swagger UI 界面如下:
@ApiImplicitParam: 方法中参数的说明
/** * 根据用户id 查询用户 * @return */ @ApiImplicitParam(paramType= "path", name = "id", value = "用户id", required = true, dataType = "Long") @GetMapping("/{id}") public User get(@PathVariable(name = "id") Long id){ //省略逻辑代码 }
访问 Swagger UI 界面如下:
@ApiImplicitParams(): 配置多个ApiImplicitParam
@ApiImplicitParams({ @ApiImplicitParam(name="name",value="用户名",dataType="string", required = true, paramType = "form",example="ljk"), @ApiImplicitParam(name="age",value="用户年龄",dataType="int", paramType = "form")}) @PostMapping() public void add(User user){ //省略逻辑代码 }
访问 Swagger UI 界面如下:
@ApiModel: 描述返回实体类信息
@ApiModel(value="user对象",description="用户对象user") public class User { }
@ApiModelProperty: 描述返回实体类属性的信息
public class User { @ApiModelProperty(value="用户名",name="name",example="xingguo") private String name; @ApiModelProperty(value="年龄1",name="age",required=true) private Integer age; }
访问 Swagger UI 界面如下:
@ApiResponse: 错误相应信息描述
@ApiResponses: 描述多个错误信息
@GetMapping("/{id}") @ApiResponses({ @ApiResponse(code = 400, message = "请求无效 (Bad request)") }) public User get(@PathVariable(name = "id") Long id){ //省略逻辑代码 }
访问 Swagger UI 界面如下:
@ApiParam: 用于声明通过request接受的参数。
@ApiIgnore(): 忽略的字段不显示在api文档中。
public void logon( @ApiParam(name="loginName",value="登录名称",required=true) @RequestParam String loginName, @ApiParam(name="password",value="密码",required=true) @RequestParam String password, @ApiIgnore()Model model,HttpServletRequest request){ }
启动 SpringBoot 项目访问:localhost:8080/sbe/swagger-ui.html 如下图所示:
我们可以在如下图中的 name 和 age 输入框中输入内容并进行测试,这里就不一个个进行测试啦。
小结
SpringBoot 整合 Swagger 需要通过SpringBoot Java Config的方式配置 Api 接口扫描的路径、接口组介绍、接口版本、接口描述等信息。接下来就是 Swagger 的具体配置注解,常用的配置注解如下:
@Api :说明接口类的作用。
@ApiOperation:用在方法上 说明方法的作用。
@ApiImplicitParam:方法中参数的说明。
@ApiImplicitParams():配置多个 ApiImplicitParam
@ApiModel:描述返回实体类信息。
@ApiModelProperty:描述返回实体类属性的信息。
@ApiResponse:错误相应信息描述。
@ApiResponses:描述多个错误信息。
@ApiParam:用于声明通过request接受的参数。
@ApiIgnore():忽略的字段不显示在api文档中。
如果你还没有操作过,可以跟着博客敲一遍哈!
代码示例
文中的代码可以参考我的 GitHub 仓库名称 springbootexamples 中的 spring-boot-2.x-swagger 进行查看
GitHub:https://github.com/zhuoqianmi...
示例程序环境版本:
SpringBoot Version:2.1.0.RELEASE
SpringMVC Version:5.1.2RELEASE
Maven Version:3.2.5
JDK Version:1.8.0_144