【springboot】集成swagger
1.简介
本章介绍 SpringBoot2.1.9 集成 Swagger2 生成在线的API接口文档。
2. pom依赖：
通过对比了swagger的几个版本，发现还是2.6.1问题最少
<!-- swagger2 依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
3. swaggerconfig配置类：
3.1 SwaggerConfig 配置类
package cn.com.wjqhuaxia.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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @Description: swagger配置类
*/
@Configuration
// 开启swagger2
// 选择不同的环境启用 swagger 以下两种方式，推荐第一种
// @Profile({"dev","test"})
// @ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("用户权限项目") // 设置项目名
.apiInfo(apiInfo())
.pathMapping("/") // 设置api根路径
.select() // 初始化并返回一个API选择构造器
.apis(RequestHandlerSelectors.basePackage("cn.com.wjqhuaxia")) // swagger api扫描的路径
.paths(PathSelectors.any()) // 设置路径筛选
.build(); // 构建
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("user-auth服务")
.description("提供用户权限功能服务接口")
.license("")
.licenseUrl("")
.termsOfServiceUrl("")
.version("1.0.0")
.build();
}
}
3.2 配置说明
一、Docket类的方法：
Docket groupName(String var):设置栏目名
Docket apiInfo(ApiInfo apiInfo):设置文档信息
Docket pathMapping(String path):设置api根路径
Docket protocols(Set<String> protocols):设置协议，Sets为com.goolge.common下的类，Sets.newHashSet("https","http")相当于new HashSet(){{add("https");add("http");}};
ApiSelectorBuilder select():初始化并返回一个API选择构造器
二、ApiSelectorBuilder类的方法：
ApiSelectorBuilder apis(Predicate<RequestHandler> selector):添加选择条件并返回添加后的ApiSelectorBuilder对象
ApiSelectorBuilder paths(Predicate<String> selector):设置路径筛选，该方法中含一句pathSelector = and(pathSelector, selector);表明条件为相与
RequestHandlerSelectors类的方法：
Predicate<RequestHandler> any()：返回包含所有满足条件的请求处理器的断言，该断言总为true
Predicate<RequestHandler> none()：返回不满足条件的请求处理器的断言,该断言总为false
Predicate<RequestHandler> basePackage(final String basePackage)：返回一个断言(Predicate)，该断言包含所有匹配basePackage下所有类的请求路径的请求处理器
三、PathSelectors类的方法：
Predicate<String> any():满足条件的路径，该断言总为true
Predicate<String> none():不满足条件的路径,该断言总为false
Predicate<String> regex(final String pathRegex):符合正则的路径
3.3 对应图示
对应以上3.1配置的简单图示
4. controller类api设置
4.1 controller配置
package cn.com.wjqhuaxia.controller;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import cn.com.wjqhuaxia.dao.IUserDao;
import cn.com.wjqhuaxia.model.UserEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
@RestController
@RequestMapping(value = "/user")
@Api(description = "用户管理接口")
public class UserManageController {
@Autowired
private IUserDao userDao;
@ApiOperation(value = "获取用户列表", notes = "获取用户列表")
@RequestMapping(value = "/getUsers", method = RequestMethod.GET)
public List<UserEntity> getUsers() {
List<UserEntity> users=userDao.getAll();
return users;
}
@ApiOperation(value = "根据用户id获取用户信息", notes = "根据用户id获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户标识", required = true, paramType = "path", dataType = "Long") })
@RequestMapping(value = "/getUser/{id}", method = RequestMethod.GET)
public UserEntity getUser(@PathVariable Long id) {
UserEntity user=userDao.getOne(id);
return user;
}
@ApiOperation(value = "新增用户" , notes="新增用户")
@RequestMapping(value = "/add", method = RequestMethod.POST)
public String save(@RequestBody UserEntity user) {
userDao.insert(user);
return "用户添加成功！";
}
@ApiOperation(value = "修改用户" , notes="修改用户")
@RequestMapping(value="update", method = RequestMethod.POST)
public void update(@RequestBody UserEntity user) {
userDao.update(user);
}
@ApiOperation(value = "删除用户" , notes="删除用户")
@RequestMapping(value="/delete/{id}", method = RequestMethod.GET)
public void delete(@PathVariable("id") Long id) {
userDao.delete(id);
}
}
4.2 配置说明
@Api()用于类； 表示标识这个类是swagger的资源 @ApiOperation()用于方法； 表示一个http请求的操作 @ApiParam()用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等） 【暂时没用，当前使用SpringMVC@RequestParam】 @ApiIgnore()用于类，方法，方法参数 表示这个方法或者类被忽略 @ApiImplicitParam() 用于方法 表示单独的请求参数 @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
4.3 图示
5. 实体类配置
5.1 实体类
/**
* 用户对象
* @author wjqhuaxia
*/
@ApiModel(value="UserEntity", description="用户对象")
public class UserEntity implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="用户id",name="id",example="1")
private Long id;
@ApiModelProperty(value="用户名",name="userName",example="mao2080")
private String userName;
@ApiModelProperty(value="密码",name="passWord",example="123456")
private String passWord;
@ApiModelProperty(value="性别",name="userSex",example="MAN")
private UserSexEnum userSex;
@ApiModelProperty(value="昵称",name="nickName",example="天际星痕")
private String nickName;
....get/set方法略。
}
5.2 配置说明
@ApiModel()用于类 表示对类进行说明，用于参数用实体类接收 @ApiModelProperty()用于方法，字段 表示对model属性的说明或者数据操作更改
5.3 简单图示
6. 测试：
访问http://localhost:8080/swagger-ui.html
注意： 访问路径有配置工程名的带上工程名，避免404。此处未配置工程名。
参考：
https://blog.csdn.net/cp026la/article/details/86501095
https://www.cnblogs.com/mao2080/p/9021714.html
https://blog.csdn.net/z28126308/article/details/71126677
