数据库文档生成工具Screw(类式Swagger)

使用场景

在工作项目中,数据库表结构文档的编辑工作一直都伴随着我们. 但是由于个人疏忽,项目赶进度以及开发人员的离职等因素,往往都存在文档与实际表结构不一致情况,这就给后续接手的开发人员，维护人员造成困扰，给他们留下遍地的坑.而Screw的出现正是替我们解决这个问题的.

Screw的特点

• 搭建方便快捷
• 支持多种数据库. 如MySQL,Oracle,SqlServer等
• 支持多种格式文档 如markdwon,Html,Word格式
• 支持用户自定义模板和展示样式

使用方式

Screw的使用有两种方式，一种是使用配置类方式，一种是插件方式
而无论是采用哪种方式，首先都要做的是添加依赖

添加依赖

<!--数据库文档核心依赖-->
  	<dependency>
      <groupId>cn.smallbun.screw</groupId>
      <artifactId>screw-core</artifactId>
      <version>1.0.4</version>
  	</dependency>
  		<!-- HikariCP -->	
  	<dependency>
      <groupId>com.zaxxer</groupId>
      <artifactId>HikariCP</artifactId>
      <version>3.4.5</version>
  	</dependency>
1
2
3
4
5
6
7
8
9
10
11
12

创建配置类

以SqlServer数据库为例

import java.util.ArrayList;

import javax.sql.DataSource;

import org.junit.Test;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

import cn.smallbun.screw.core.Configuration;
import cn.smallbun.screw.core.engine.EngineConfig;
import cn.smallbun.screw.core.engine.EngineFileType;
import cn.smallbun.screw.core.engine.EngineTemplateType;
import cn.smallbun.screw.core.execute.DocumentationExecute;
import cn.smallbun.screw.core.process.ProcessConfig;




public class ScrewConfig {
	@Test
	public void shouldAnswerWithTrue() {
	    //数据源
	    HikariConfig hikariConfig = new HikariConfig();
	    hikariConfig.setDriverClassName("net.sourceforge.jtds.jdbc.Driver");//项目中使用的DriverClassName
	    hikariConfig.setJdbcUrl("jdbc\\:jtds\\:sqlserver\\://127.0.0.1\\:1433/数据库名称;useLOBs\\=false");//项目中使用的jdbcUrl
	    hikariConfig.setUsername("用户名");
	    hikariConfig.setPassword("密码");
	    //设置可以获取tables remarks信息
	    hikariConfig.addDataSourceProperty("useInformationSchema", "true");
	    hikariConfig.setMinimumIdle(2);
	    hikariConfig.setMaximumPoolSize(5);
	    DataSource dataSource = new HikariDataSource(hikariConfig);
	    //生成配置
	    EngineConfig engineConfig = EngineConfig.builder()
	            //生成文件路径
	            .fileOutputDir("/Users/lengleng")
	            //打开目录
	            .openOutputDir(true)
	            //文件类型
	            .fileType(EngineFileType.HTML)
	            //生成模板实现
	            .produceType(EngineTemplateType.freemarker).build();

	    //忽略表
	    ArrayList<String> ignoreTableName = new ArrayList<>();
	    ignoreTableName.add("test_user");
	    ignoreTableName.add("test_group");
	    //忽略表前缀
	    ArrayList<String> ignorePrefix = new ArrayList<>();
	    ignorePrefix.add("test_");
	    //忽略表后缀
	    ArrayList<String> ignoreSuffix = new ArrayList<>();
	    ignoreSuffix.add("_test");
	    ProcessConfig processConfig = ProcessConfig.builder()
	            //忽略表名
	            .ignoreTableName(ignoreTableName)
	            //忽略表前缀
	            .ignoreTablePrefix(ignorePrefix)
	            //忽略表后缀
	            .ignoreTableSuffix(ignoreSuffix).build();
	    //配置
	    Configuration config = Configuration.builder()
	            //版本
	            .version("1.0.0")
	            //描述
	            .description("数据库设计文档生成")
	            //数据源
	            .dataSource(dataSource)
	            //生成配置
	            .engineConfig(engineConfig)
	            //生成配置
	            .produceConfig(processConfig).build();
	    //执行生成
	    new DocumentationExecute(config).execute();
	}

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

以JUnit Test方式测试运行即可看到效果.

插件方式

以MySQL数据库为例

<build>
    <plugins>
        <plugin>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-maven-plugin</artifactId>
            <version>${lastVersion}</version>
            <dependencies>
                <!-- HikariCP -->
                <dependency>
                    <groupId>com.zaxxer</groupId>
                    <artifactId>HikariCP</artifactId>
                    <version>3.4.5</version>
                </dependency>
                <!--mysql driver-->
                <dependency>
                    <groupId>mysql</groupId>
                    <artifactId>mysql-connector-java</artifactId>
                    <version>8.0.20</version>
                </dependency>
            </dependencies>
            <configuration>
                <!--username-->
                <username>root</username>
                <!--password-->
                <password>password</password>
                <!--driver-->
                <driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
                <!--jdbc url-->
                <jdbcUrl>jdbc:mysql://127.0.0.1:3306/xxxx</jdbcUrl>
                <!--生成文件类型-->
                <fileType>HTML</fileType>
                <!--打开文件输出目录-->
                <openOutputDir>false</openOutputDir>
                <!--生成模板-->
                <produceType>freemarker</produceType>
                <!--文档名称 为空时:将采用[数据库名称-描述-版本号]作为文档名称-->
                <fileName>测试文档名称</fileName>
                <!--描述-->
                <description>数据库文档生成</description>
                <!--版本-->
                <version>${project.version}</version>
                <!--标题-->
                <title>数据库文档</title>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>run</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

需要注意的是Screw的使用需要jdk1.8的环境，如果你的项目是1.7的那么可能会报如下错误:Unsupported major.minor version 51.0 / 52.0

效果

参考：
Screw在码云上的地址