API文档生成之Springfox-Swagger框架的简单使用 |我的资源库露水湾

后端开发一定厌倦了和前端对API接口的麻烦，之前还是小白时愣是手写 word 文档给前端工程师使用，各种 copy 字段加解释…

然而，有更好用的API框架可以使用，可以让我们摆脱这种烦恼，下面说下 spring-fox swagger 的简单使用
注：swagger 是一种API规范，springfox 是其规范的一种实现

引入 swagger 依赖

<!– https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 –>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<!– https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui –>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>

配置 swagger，本例中使用的是 springboot 配置，如需 xml 配置请自行百度
编写SwaggerConfig
添加注解
@Configuration
@EnableSwagger2
Docket.apis()中配置的包名为要扫描生成API的 Controller 包名，将会为该包下的 controller 生成相关文档
ApiInfo 为相关信息，该信息将会展示在文档中

/**
* Created by wangqichang on 2018/6/22.
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig{
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(“com.kichun.controller”))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title(“炒鸡好用的系統API“)
.description(“更多内容请咨询开发者王启昌”)
.termsOfServiceUrl(“http://kichun.xin/”)
.contact(“wangqichang”)
.version(“1.0”)
.build();
}
}

在需要添加的 controller 类和方法中加上 api 注解
加在类上
@Api(value = “字典操作接口”,tags = {“字典常量操作”})
加在方法上
@ApiOperation(value = “删除字典类型”,notes = “”)
@ApiImplicitParam(name = “id”,value = “字典 ID”,required = true,dataType = “String”)

/**
* <p>
* 前端控制器
* </p>
*
* @author wangqichang
* @since 2018-06-15
*/
@Api(value = “字典操作接口”,tags = {“字典常量操作”})
@RestController
@RequestMapping(“/dataDict”)
public class DataDictController{
@Autowired
private DataDictService dataDictService;
/**
* 删除字典类型
*
* @author Qichang.Wang
* @date 16:04 2018/6/15
*/
@ApiOperation(value = “删除字典类型”,notes = “”)
@ApiImplicitParam(name = “id”,value = “字典 ID”,required = true,dataType = “String”)
@RequestMapping(value = “/delete”, method = RequestMethod.POST)
public ResultDTO delete(String id) {
if (StrUtil.isBlank(id)) {
return new ResultDTO(400, “参数异常”);
}
BaseDictEnum baseDictEnum = BaseDictEnum.fromId(id);
if (baseDictEnum != null) {
return new ResultDTO(500, “暂不支持删除顶级字典！”);
}
boolean insert = dataDictService.deleteById(id);
return insert ? new ResultDTO(200, “success”) : new ResultDTO(500, “fail”);
}

当有多个参数时用@ApiImplicitParams

/**
* 登录
*
* @author Qichang.Wang
* @date 17:27 2018/6/14
*/
@ApiOperation(value = “用户登录接口”, notes = “”)
@ApiImplicitParams(value = { @ApiImplicitParam(name = “name”, value = “用户名”, required = true),
@ApiImplicitParam(name = “pwd”, value = “密码”, required = true),
@ApiImplicitParam(name = “rememberMe”, value = “勾选时传递 true”, required = false) })
@RequestMapping(value = “/login”, method = RequestMethod.POST)
public ResultDTO login(String name, String pwd, String rememberMe){
if (StrUtil.isBlank(name) || StrUtil.isBlank(pwd)) {
return new ResultDTO(500, “用户名及角色不能为空”);
}
Boolean remember = false;
if (StrUtil.isNotBlank(rememberMe) || “true”.equals(rememberMe.trim())) {
remember = true;
}
UsernamePasswordToken token = new UsernamePasswordToken(name, pwd, remember);
try {
SecurityUtils.getSubject().login(token);
} catch (Exception e) {
log.error(“登录失败，信息：{}”, e.getMessage());
return new ResultDTO(401, “登录失败, 用户名或密码不匹配”);
}
return new ResultDTO(200, “登录成功！”);
}

当参数是个对象时，参数前加入
@RequestBody @ModelAttribute
这样才能将对象的属性给到 swagger

* 新增更新字典类型
*
* @author Qichang.Wang
* @date 16:05 2018/6/15
*/
@ApiOperation(value = “新增及更新字典”,notes = “对象包含 ID 时为更新，不包含 ID 时为新增”)
@ApiImplicitParam(name = “dict”,value = “字典对象,详细请查看对象属性”,required = true,dataType = “DataDict”)
@RequestMapping(value = “/update”, method = RequestMethod.POST)
public ResultDTO update(@RequestBody @ModelAttribute DataDict dict){
if (StrUtil.isBlank(dict.getParentId()) || StrUtil.isBlank(dict.getName())) {
return new ResultDTO(400, “参数异常”);
}
BaseDictEnum baseDictEnum = BaseDictEnum.fromId(dict.getId());
if (baseDictEnum != null) {
return new ResultDTO(500, “暂不支持修改顶级字典！”);
}
if (StrUtil.isBlank(dict.getId())){
DataDict exist = new DataDict();
exist.setName(dict.getName());
exist.setParentId(dict.getParentId());
List<DataDict> dataDicts = dataDictService.selectList(new EntityWrapper<>(dict));
if (CollUtil.isNotEmpty(dataDicts)) {
return new ResultDTO(500, “该类型名已存在”);
}
dataDictService.insert(dict);
} else {
boolean insert = dataDictService.updateById(dict);
}
return new ResultDTO(200,“操作成功”);
}

注解的各个属性相信各位大佬一看就能明了，不多加解释了
加好注解后，重启应用
接下来是见证奇迹的时候
访问路径：应用地址+端口+swagger-ui.html 例如http://localhost:8800/swagger-ui.html

image.png

展开 contoller 效果

image.png

展开接口效果

image.png

点 try it out 可以直接对接口进行测试，彻底抛弃什么 Postman，RestfulClient 等调试工具！

只要注释写的全，再复杂的应用统统搞定有没有！！！
改了接口自动重新生成API文档有没有！！！
会写代码的前端工程师都能看懂有没有！！！
还是看不懂的前端直接打屎算了有没有！！！

美中不足是字段详细我还不确定能不能加注释，你们研究下吧，我觉得达到这效果已经 OK 了

20180921 补充：
针对接口请求对象及返回对象使用上述方式无法展示字段说明。使用@ModelAttribute 注解可能会导致一些莫名错误无法获取参数

实体注解

@ApiModel 用于实体类上，标注为需要生成文档的实体
@ApiModelProperty(value = “url 菜单”,required = true) 用于实体属性，标注该属性的说明，require 为 false 时不会在页面上进行展示该属性

import com.baomidou.mybatisplus.enums.IdType;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* <p>
* 权限表
* </p>
*
* @author wangqichang
* @since 2018-06-14
*/
@Data
@Accessors(chain = true)
@TableName(“t_resource”)
@ApiModel
public class Resource extends Model<Resource> {
private static final long serialVersionUID = 1L;
/**
* 资源 ID
*/
@TableId(type = IdType.UUID)
@ApiModelProperty(hidden = true)
private String id;
/**
* url
*/
@ApiModelProperty(value = “url 菜单”,required = true)
private String url;
/**
* 父 ID
*/
@TableField(“parent_id”)
@ApiModelProperty(hidden = true)
private String parentId;
/**
* 资源名
*/
@TableField(“resource_name”)
@ApiModelProperty(value = “资源名”,required = true)
private String resourceName;
/**
* 资源类型(menu,btn)
*/
@TableField(“resource_type”)
@ApiModelProperty(value = “资源类型(menu,btn)”,required = true)
private String resourceType;
/**
* 资源码
*/
@TableField(“resource_code”)
@ApiModelProperty(value = “资源码”,required = true)
private String resourceCode;
/**
* 资源描述
*/
@TableField(“resource_desc”)
@ApiModelProperty(value = “资源描述”,required = true)
private String resourceDesc;
/**
* 菜单图标
*/
@ApiModelProperty(value = “菜单图标”,required = true)
private String myicon;
/**
* 是否可用
*/
@ApiModelProperty(hidden = true)
private Integer available;
/**
* 创建时间
*/
@TableField(“create_time”)
@ApiModelProperty(hidden = true)
private Date createTime;
/**
* 创建人 id
*/
@TableField(“create_id”)
@ApiModelProperty(hidden = true)
private Date createId;
/**
* 排序
*/
@ApiModelProperty(value = “资源排序”,required = true)
private Integer sort;
/**
* 临时字段，供前端选中使用
*/
@TableField(exist = false)
@ApiModelProperty(hidden = true)
private Boolean isChecked;
@Override
protected Serializable pkVal() {
return this.id;
}
}

在实体添加注解后，在接口中使用如下注解

@ApiParam(name = “资源对象”,value = “json 格式”,required = true)
标识该对象为文档实体

@ApiOperation(value = “权限资源新增及更新”, notes = “有 ID 更新，没 ID 为新增”)
@RequestMapping(value = “/resource”, method = RequestMethod.POST)
public ResultDTO resource(@RequestBody @ApiParam(name = “资源对象”,value = “json 格式”,required = true) Resource resource) {
Integer count = 0;
try {
count = userService.updateResources(resource);
} catch (Exception e) {
log.error(“新增或更新资源异常：{}”, e.getMessage());
return new ResultDTO(500, e.getMessage());
}
return count > 0 ? new ResultDTO(200, “保存成功”) : new ResultDTO(500, “操作失败，请查询日志”);
}

实体注释文档界面

需要点击 model 才会显示说明

image.png

效果如下

image.png

关于 shiro 权限拦截

使用中发现开启 shiro 后无法访问 swagger api 界面
问题原因：swagger 内置接口被权限拦截导致无法访问
处理方式：
浏览器打开 F12 调试，选择 network，查看 status 为非 200 的以 swagger、springfox、apidoc 开头的 URL，记录该 URL 并在权限拦截中放行

image.png

例如 shiro，在 ShiroFilter 中放行以下 URL。注意不同版本的 swaggerURL 略有区别，请以上面的方式查看具体需放行的 URL

filterChainDefinitionMap.put(“/swagger-ui.html”, “anon”);
filterChainDefinitionMap.put(“/swagger-resources/**”, “anon”);
filterChainDefinitionMap.put(“/v2/api-docs”, “anon”);
filterChainDefinitionMap.put(“/webjars/springfox-swagger-ui/**”, “anon”);

前后分离之 Authorization 请求头设置

在前后分离项目中部分项目会使用到 jwt 或者其他方式在 header 中传递令牌 token 的方式，需要 swagger 添加相关配置加入请求头

在 swaggerConfig 中，加入全局 header 设置，参考如下代码

/**
* Created by wangqichang on 2018/9/25.
*/
@Slf4j
@Configuration
@EnableSwagger2
public class SwaggerConfig{
@Value(“${SwaggerSwitch:false}”)
private boolean SwaggerSwitch;
@Bean
public Docket createRestApi(){
log.info(“========================================== 当前环境是否开启 Swagger：” + SwaggerSwitch);
return new Docket(DocumentationType.SWAGGER_2)
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.enable(SwaggerSwitch)
.apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage(“com.seebon.vip.csp.server.web.controller.rest”)).paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder().title(“VIP 后台系统 API”).description(“新后台 Restful 接口”).termsOfServiceUrl(“http://www.xxx.com”)
.version(“1.0”).build();
}
/**
* swagger 加入全局 Authorization header 将在 ui 界面右上角新增 token 输入界面
* @return
*/
private List<ApiKey> securitySchemes(){
ApiKey apiKey = new ApiKey(“Authorization”, “Authorization”, “header”);
ArrayList arrayList = new ArrayList();
arrayList.add(apiKey);
return arrayList;
}
/**
* 在 Swagger2 的 securityContexts 中通过正则表达式，设置需要使用参数的接口（或者说，是去除掉不需要使用参数的接口），
* 如下列代码所示，通过 PathSelectors.regex(“^(?!auth).*$”)，
* 所有包含”auth”的接口不需要使用 securitySchemes。即不需要使用上文中设置的名为“Authorization”，
* type 为“header”的参数。
*
*/
private List<SecurityContext> securityContexts(){
SecurityContext build = SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.any())
.build();
ArrayList arrayList = new ArrayList();
arrayList.add(build);
return arrayList;
}
List<SecurityReference> defaultAuth(){
AuthorizationScope authorizationScope = new AuthorizationScope(“global”, “accessEverything”);
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
SecurityReference authorization = new SecurityReference(“Authorization”, authorizationScopes);
ArrayList arrayList = new ArrayList<>();
arrayList.add(authorization);
return arrayList;
}
}

加入以上代码后，swagger-ui 界面右上角将出现如图图标

image.png

点击该图标，在 value 中输入登录返回的 token

image.png

然后请求任何接口，都会带上一个名为 Authorization，值为输入值（例如本文中的 token）的请求头了

image.png

踩坑记录

采坑 1
项目使用了 sitemesh 时，需要在 decorators.xml 中把上述资源进行排除，否则会影响到 swagger-ui 资源的访问，导致 swagger-ui 界面无内容

采坑 2
在自定义权限控制中，访问/swagger-resources/configuration/ui 资源时 404，原因为通过@EnableSwagger2 时会自动扫描到一个 ApiResourceController 类，该类有个资源路径为/configuration/ui
而在自定义权限控制中该路径被拦截返回错误导致 404