秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇

原创不易,请多多支撑。对java技能感兴趣的童鞋请重视我,后续将连续推出各类java技能文章。

概述

现在团队项目盛行前后端别离的开发形式,前台技能担任展现逻辑,后端技能担任接口完结。责任别离,并行开发,互不搅扰。大大提高了作业效率,缩短了项目开发周期。这种形式中,Api接口的文档界说,成为了前后端团队交互的要害。

有过后端开发经历的码农,应该深有体会Api接口文档的编写是一件多么繁琐的作业。特别经过word文档交互的办法,半途若发作改变,需求从头更新文档,并告诉到相关人。项目团队规划不大,接口不多时,这种形式也能满足要求。当项目堆集到必定阶段,团队规划胀大到必定数量时,就会发现对api文档的维护将成为一件让人不胜其扰的作业,在项目开发过程中糟蹋掉很多时刻。

多年的开发体会,对频频重复的作业,能用程序处理的就不要用人力。根据以上痛点,本文将向咱们引荐swagger和mybatis-generator结构整合api文档的实践。让编写api文档的繁琐作业从日常开发中脱离出来。

完结思路

swagger是一款很赞的API文档完结结构。mybatis-generator是一个数据库db模型逆向生成mybatis dao的插件。

完结思路,经过mybatis-generator插件将DB表动态生成java model目标时,主动把表字段的注释内容,按swagger中的@ApiModelProperty注解办法增加到model目标特点上。针对大部分接口的输入输出,若能复用model目标,开发人员无需花时刻去写每个特点的中文描绘了,只需求在新建数据库表结构时界说好每个字段的中文注释,剩余的就交给程序完结。

Swagger集成

增加包依靠


com.github.xiaoymin
swagger-bootstrap-ui
1.9.3


io.springfox
springfox-swagger2
2.9.2

这儿没有运用springfox-swagger-ui,而挑选swagger-bootstrap-ui。个人更习气swagger-bootstrap-ui的左右布局的界面交互办法。

增加springboot config类

**
* Cre囊ated by eagle.daiq on 2019/5/12.
*/
@Configuration皇七子永琮
@EnableSwagger2
public class SwaggerConfiguration {
@Value(港娱之打造芒果王朝"${swagger.enable}")
private boolean enableSwagger;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(enableSwagger) // Flag to 天鹅臂分化动作图片enable or disable possibly loaded using a property file
.select()
//为当时包途径
.apis(RequestHandlerSelectors.basePackage("com.dctl.ea.demo.app"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的具体信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("后台Api接口")
//创建人
.contact(new Contact("dctl-demo", "www.demo.com", "eagle_daiqiang@sina.com"))
//版别号
.version("1.0")
//描绘
.d秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇escription("后台API")
.build();
}
}

swagger集成完结。Api接口界说先不做,等mybatis-generator集成好了再一致完结。

mybatis-generator扩展

这儿需求在db表逆向生成java model时,动态增加swagger的@ApiModelProperty注解。mybatis-generator原生插件不支撑,需求自界说扩展完结。因为类加载报错的原因,mybatis-generator就不必maven插件办法,经过在java中调用api办法完结。

mybatis-generator依靠增加


org.mybatis.generator
mybatis-generator-core
1.3.2

工程resource目录新建以下2个文件。

config.properties是generator生成装备的公共特点装备。概况如下:

# 通用Ma格兰仕pper装备
jdbc.driverClass=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/dctl_demo?useUnicode=true&characterEncoding=秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇utf-8&zeroDateTimeBehavior=convertToNull&transformedBitIsBoolean=true
jdbc.user=root
jdbc.password=root
#java模型生成目录
targetModelPackage=com.dctl.ea.demo.app.user.model.gen
#mybatis xml文件生成目录
targetXMLPackage=mapper.gen
#mybatis dao mapper生成目录
targetMapperPackage=com.dctl.ea.demo.app.user.dao.gen

generatorConfig.xml文件内容如下:



PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
"http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">















connectionURL="${jdbc.url}"
userId="${jdbc.user}"
password="${jdbc.password}">







targetProject="dctl-demo/src/main/java">





targetProject="dctl-demo/src/main/resources/">




targetPackage="${targetMapperPackage}"
targetProject="dctl-demo/src/main/java">








以上装备内容需留意以下元素界说:

classPathEntry: 界说数据库驱动文件。因为mybatis generator运用java类调用api办法,需把相关依靠增加到类途径下,不然会报找不到驱动文件过错。

commentGenerator: 注释元素。其间type指定生成java model注释的完结类。这儿是自界说完结。后面会触及警察故事该类具体完结。

javaModelGenerator、sqlMapGenerator、javaClientGenerator元素中的targetProject特点,设置值为{项目名}/src/main/java、{项目名}/src/main/resources、{项目名}/src/main/java。其间{项目名}请自行替换为实践项目名。直接写src/main/java,针对多模块的项目或许找不到。

DbColumnCommentGenerator扩展完结

新建DbColumnCommentGenerator类,承继DefaultCommentGenerator。该类为mybatis-generator生成java model时,增加swagger注解的完结。


import org.mybatis.generator.api.IntrospectedColumn;
import org.mybatis.generator.api.IntrospectedTable;
import org.mybatis.generator.api.dom.java.*;
import org.mybatxxxx日本is.generator.api.dom.xml.XmlElement;
import org.mybatis.generator.internal.DefaultCommentGenerator;
/**
* Author: daiqiang
* Date:秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇 2019/5/8
* Description: No Description
*/
public class DbCo创生之柱lumnCommentGenerator extends DefaultCommentGenerator {
private boolean suppressAllComments;
public void addJavaFileComment(CompilationUnit compilationUnit) {
if (suppressAllComments) {
return;
}
FullyQualifiedJavaType apiModelProperty = new FullyQualifiedJavaType("io.swagger.annotations.ApiModelProperty;");
compilationUnit.addImportedType(apiModelProperty);
return;
}
/**
* 字段特点注释
*/
public void a邝宝强ddFieldComment(Field field, IntrospectedTable introspectedTable,
IntrospectedColumn introspectedColumn) {
if (suppressAllComments) {
return;
}
StringBuilder sb = new StringBuilder();
field.addJavaDocLine("/**班淑传奇");
sb.append(" * ");
sb.append(introspectedColumn.getRemarks());
fi日姐妹eld.addJavaDocLine(sb.toString());
field.addJavaDocLine(" */");
// @ApiMode秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇lProperty(value="状况",name="state",required=true)
field.addJavaDocLine("@ApiModelProperty(value=\""+intro秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇spectedColumn.getRemarks()+"\")");
}
/**
* get办法注释
*/
public void addGetterComment(Method method, IntrospectedTable introspectedTable,
IntrospectedColumn introspectedColumn) {
if (suppressAllComments) {
return;
}
method.addJavaDocLine("/**");
StringBuilder sb = new StringBuilde秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇r();
sb.append(" * 获取 ");
sb.append(introspectedColumn.getRemarks());
method.addJavaDocLine(sb.toString());
sb.setLength(0);
sb.a猪八戒背媳妇ppend(" * @return ");
sb.append(introspectedColumn.getActualColumnName());
meth集od.addJavaDocLine(sb.toString());
method.addJavaDocLine(" */");
}
/**
* set注释
*/
public void addSetterComment(Method method, IntrospectedTable introspectedTable,
IntrospectedColumn introspectedColumn) {
if (suppressAllComments) {
return;
}
method.addJavaDocLine("/**");
StringBuilder sb = new StringBuilder();
sb.append(" * 设置 ");
sb.append(introspectedColumn.getRemarks());
method.addJavaDocLine(sb.toString());
Parameter parm = method.getParameters().get(0);
sb.setLength(0);
sb.append(" * @param ");
sb.append(parm.getName());
method.addJavaDocLine(sb.toString());
method.addJavaDocLine(" */");
}
// 增加xml文件的注释("彻底反人类 没用")
public void addComment(XmlElement xmlElement) {
if (suppres创世纪sAllComments) {
return;
}
}
}

新建mybatis-generator生成文件进口类MybatisDbGenerator

import org.mybatis.generator.api.MyBatisGenerator;
import org.mybatis.generator.魔兽国际官网config.Configuration;
import org.mybatis.generator.config.xml.ConfigurationParser;
import org.mybatis.generator.internal.DefaultShellCallback;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
/**
* Author: daiqiang
* Date: 2019/5/8
* Description: No Description
*/
public class MybatisDbGenerator {
public static void main( String[] args ) throws Exception {
System.out.println(MybatisDbGenerator.class.getResource("/").getPath());
System.out.println(System.getProperty("user.dir"));
List warnings = new ArrayList();
boolean overwrite = true;
InputStream resourceAsStream = MybatisDbGenerator.class.getClassLoader().getResourceAsStrea伊斯兰国m("generator/generatorConfig.xml");
ConfigurationParser cp = new ConfigurationParser(warnings);
Configuration config = cp.parseConfiguration(resourceAsStream);
DefaultShellCallback callback = new DefaultShellCallback(overwrite);
MyBatisGenerator myBatisGenerator = new MyBatisGenerator(config, callback, warnings);
myBatisGenerator.generate(null);
for(String warning:warning天然常数为什么恐惧s){
System.out.println(warning);
}
}
}

到此,swagger和mybatis-generator插件集成已完结。下面咱们以体系app装备表为例,来看一看逆向生成api的作用。

DB表结构

新增sys_app使用装备表,留意界说每列的中文注释。

增加上述表映射关系到generatorConfig.xml中




运转MybatisDbGenerator 类main办法。履行完结后,在映射对应方位将生成SysApp类。

新建SysAppController类。

@RestController
@RequestMapping("/sys")
@Api(tags = "体系使用办理")
public class SysAppController {
@Autowired
private SysAppService sysAppService;
@ApiOp秦卫江,swagger2和mybatis-generator集成Api接口文档实践,黑寡妇eration(value = "获取体系使用信息")
@RequestMapping(value = "/info/get",method = Requ颈椎estMethod.GET)
public DefaultResponseVo getSysApp(String sysId, HttpServletRequest request){
AssertParams.isNumber(sysId,"sysId parameter is not allowed empty.");
SysApp sysApp = this.sysAppService.getSysAppById(Integer.valueOf(sysId));
return DefaultResponseVo.success("SUCCESS",sysApp);
}
}

其间pk绝版皇室美男团回来成果目标为SysApp。发动springboot项目,发动成功后浏览器拜访以下地址。

http://localhost:8082/doc.html

布置正常的话将显现如下页面内容。

截图中能够看到新增的api接口信息,现已经过swagger主动进行了接口字段内容描绘。只需数据库字段界说具体,接口的入参、出参将无需独自描绘。

经过swagger和mybatis-generator的集成,主动对Api接口文档描绘,是不是有了如虎添翼的感觉?! 该计划欠好的当地,为了扩展mybatis-generator中comment注释类,从maven插件办法改成了java类的完结,和运转时的事务代码耦合在了一块,在高雅性方面稍差了些。因为时刻原因,未能进一步研讨maven mybatis-generator 插件的扩展实践办法。若有更好计划的码友,请多多指教。

对java技能感兴趣的童鞋,请重视我。原创不易,请多多支撑,谢谢!