springboot：接手老项目，领导让更新数据库说明文档，如何3分钟完成任务

0 引言

最新在重新整理老项目的文档，其中数据库说明文档上一版更新还是在1年多前，文档中的数据结构说明与当前数据库严重脱节，所以更新数据库说明文档已经是迫在眉睫的事情了。

因为项目是一个比较大型且“年长‘的项目，涉及了多个数据库，N多张表，所以作为一个好（懒）的开发者，一张表一张表手写是不可能，当然可以通过sql导出表结构，但是依然很慢。

能不能有一个工具，能帮我自动生成数据库说明文档，当然是有的，今天我们就来说一说数据库中的swagger——screw组件

1. screw简介

screw是用来生成数据库表结构说明文档的组件，通过引用jar包，通过简单的配置就可以自动生成文档，相当于数据库中的swagger，支持html, word, md三种格式的文档

2. screw使用

1、创建springboot项目，引入依赖：

• 因为我们要作为一个springboot web项目运行，所以引入spring web
• 因为要使用mysql连接驱动器，所以引入mysql-connector-java
• screw-core和HikariCP是screw组件使用需要的依赖
• 最后，我们需要用单元测试的方式来调用生成文档的方法，所以需要spring-boot-starter-test依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>

        <!-- screw核心 -->
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-core</artifactId>
            <version>1.0.5</version>
        </dependency>
        <!-- HikariCP -->
        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>3.4.5</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

2、

application.yml

配置文件配置数据库连接信息，同时开启

xa.properties.useInformationSchema

，该配置用于开启读取表注释（remarks）信息

spring:application:name: datebase_doc_demo
  datasource:driver-class-name: com.mysql.cj.jdbc.Driver
    name: defaultDataSource
    url: jdbc:mysql://localhost:3306/bladex?serverTimezone=UTC
    username: root
    password:123456xa:properties:useInformationSchema:true

3、创建生成文档代码

importcn.smallbun.screw.core.Configuration;importcn.smallbun.screw.core.engine.EngineConfig;importcn.smallbun.screw.core.engine.EngineFileType;importcn.smallbun.screw.core.engine.EngineTemplateType;importcn.smallbun.screw.core.execute.DocumentationExecute;importcn.smallbun.screw.core.process.ProcessConfig;importorg.junit.jupiter.api.Test;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.boot.test.context.SpringBootTest;importorg.springframework.context.ApplicationContext;importjavax.sql.DataSource;importjava.util.ArrayList;importjava.util.Arrays;importjava.util.List;@SpringBootTestclassDatebaseDocDemoApplicationTests2{@AutowiredprivateApplicationContext applicationContext;@TestvoidgenerateDBDoc2(){DataSource dataSource = applicationContext.getBean(DataSource.class);EngineConfig engineConfig =EngineConfig.builder()//生成文件路径.fileOutputDir("/Users/wuhanxue/Downloads")// 打开目录.openOutputDir(true)// 文件类型，支持word、md和html.fileType(EngineFileType.HTML)//生成模板实现，支持freemarker和velocity.produceType(EngineTemplateType.freemarker).build();//生成配置文档Configuration configuration =Configuration.builder().version("1.0.0").description("数据库说明文档").dataSource(dataSource).engineConfig(engineConfig).produceConfig(getProcessConfig()).build();//执行生成newDocumentationExecute(configuration).execute();}/**
     * 配置想要生成的表 + 配置想要忽略的表
     * @return
     */privateProcessConfiggetProcessConfig(){// 忽略表名List<String> ignoreTable =Arrays.asList("test_xxx");//忽略表前缀，如忽略a开头的数据库表List<String> ignorePrefix =Arrays.asList("test_");//忽略表后缀List<String> ignoreSuffix =Arrays.asList("_test");returnProcessConfig.builder()// 根据名称生成指定表.designatedTableName(newArrayList<String>())// 根据表前缀生成.designatedTablePrefix(newArrayList<String>())// 根据表后缀生成.designatedTableSuffix(newArrayList<String>())// 忽略表名.ignoreTableName(ignoreTable)// 忽略表前缀.ignoreTablePrefix(ignorePrefix)// 忽略表后缀.ignoreTableSuffix(ignoreSuffix).build();}}

当然这个是需要springboot项目的配置文件配置的，如果你是spring项目引入的，或者其他纯maven项目引入，也可以通过一下代码生成

importcn.smallbun.screw.core.Configuration;importcn.smallbun.screw.core.engine.EngineConfig;importcn.smallbun.screw.core.engine.EngineFileType;importcn.smallbun.screw.core.engine.EngineTemplateType;importcn.smallbun.screw.core.execute.DocumentationExecute;importcn.smallbun.screw.core.process.ProcessConfig;importcom.zaxxer.hikari.HikariConfig;importcom.zaxxer.hikari.HikariDataSource;importorg.junit.jupiter.api.Test;importorg.springframework.boot.test.context.SpringBootTest;importjavax.sql.DataSource;importjava.util.ArrayList;@SpringBootTestclassDatebaseDocDemoApplicationTests{@TestvoidgenerateDBDoc(){HikariConfig hikariConfig =newHikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl("jdbc:mysql://localhost:3306/bladex?serverTimezone=UTC");
        hikariConfig.setUsername("root");
        hikariConfig.setPassword("123456");// 设置可以获取remark信息
        hikariConfig.addDataSourceProperty("useInformationSchema","true");
        hikariConfig.setMinimumIdle(2);
        hikariConfig.setMaximumPoolSize(5);DataSource dataSource =newHikariDataSource(hikariConfig);// 生成配置EngineConfig engineConfig =EngineConfig.builder()// 生成文件路径.fileOutputDir("/Users/wuhanxue/Downloads")// 打开目录 设置为true执行完代码后会自动打开对应路径文件夹.openOutputDir(true)// 文件类型,支持三种类型//                .fileType(EngineFileType.HTML).fileType(EngineFileType.WORD)// 生成模板实现.produceType(EngineTemplateType.freemarker).build();// 忽略表,这些表不会在文档中生成ArrayList<String> ignoreTableName =newArrayList<>();
        ignoreTableName.add("test_xxx");// 忽略表前缀,这些表不会在文档中生成ArrayList<String> ignorePrefix =newArrayList<>();
        ignorePrefix.add("test_");// 忽略表后缀,这些表不会在文档中生成ArrayList<String> ignoreSuffix =newArrayList<>();
        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();// 执行生成newDocumentationExecute(config).execute();}}

4、运行测试

• html格式

• word格式

• md格式

源码

文中源码可在如下地址下载：

git地址

总结

如上所示，我们的数据库说明文档就做完了，当然我在实际项目中的数据库比上述演示的要大的多，但数据库越大，我们省的时间就越多

但是大家也要把握screw组件的适用场景，有的人会觉得它很鸡肋，因为我们实际开发时是先写数据库设计文档，再开发的，但有的场景，比如接手老项目，或者项目迭代比较快的，数据库文档更新不及时时，就可以使用这个组件来帮助我们自动生成文档

这里大家还可以继续做拓展，将生成方法包装为一个接口，通过监控binlog中的DDL语句，来触发接口调用，从而实现自动生成数据库文档，可以通过生成html格式的，放到后台项目中，这样就实现了实时自动更新的数据库说明文档