資料庫界的Swagger：一鍵生成資料庫文檔！

2022 年 5 月 6 日
筆記
【Study】-- Tool

對於開發的API文檔，我們可以通過Swagger等工具來自動生成了。但是對於資料庫表結構的文檔呢，在實際開發中在開發前我們一般會先設計好表結構，大家討論一下，

這個時候就很需要有個資料庫表結構的文檔，如果常規操作就是一通無腦的 CV 大法，產出一份小几十頁的 Word 文檔,這樣不僅容易出錯，而且如果表結構變了還需修改

Word文檔，非常不方便。

這裡介紹並演示一個開源的生成資料庫表結構的文檔的工具，可以幫我們高效的自動生成資料庫表結構文檔。

工具名稱: screw。

開源地址: //gitee.com/leshalv/screw。

有興趣的朋友可以研究下源碼，沒興趣就直接拿來用就好了。

一、 screw 簡介

screw 是一個簡潔好用的資料庫表結構文檔的生成工具，支援 MySQL、Oracle、PostgreSQL 等主流的關係資料庫。

生成的文檔有 HTML、Word、Markdown 三種格式，示例如下圖所示：

1、Html演示效果

2、Word演示效果

3、Markdown演示效果

看完演示效果，我們接下來看看如果生成 資料庫文檔，其實非常簡單，我們下面示範下。

二、快速入門

screw 有兩種方式來生成文檔，通過 Java程式碼 或者 Maven插件 。

下面，我們來分別快速入門下。

1、使用 Java 程式碼的方式

1、引入pom文件

    <dependencies>
        <dependency>
            <groupId>cn.smallbun.screw</groupId>
            <artifactId>screw-core</artifactId>
            <version>1.0.5</version>
        </dependency>
        <!-- 資料庫連接 -->
        <dependency>
            <groupId>com.zaxxer</groupId>
            <artifactId>HikariCP</artifactId>
            <version>3.4.5</version>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.22</version>
        </dependency>
    </dependencies>

2、實現工具類

public class ScrewUtil {

    public static void main(String[] args) {
        ScrewUtil.documentGeneration();
    }
    /**
     * 文檔生成
     */
   static void documentGeneration() {
        //數據源
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl("jdbc:mysql://localhost:3306/mall_order");
        hikariConfig.setUsername("root");
        hikariConfig.setPassword("root");
        //設置可以獲取tables remarks資訊
        hikariConfig.addDataSourceProperty("useInformationSchema", "true");
        hikariConfig.setMinimumIdle(2);
        hikariConfig.setMaximumPoolSize(5);
        DataSource dataSource = new HikariDataSource(hikariConfig);
        //生成配置
        EngineConfig engineConfig = EngineConfig.builder()
                //生成文件路徑
                .fileOutputDir("你的生成文件地址")
                //打開目錄
                .openOutputDir(true)
                //文件類型
                .fileType(EngineFileType.HTML)
                //生成模板實現
                .produceType(EngineTemplateType.freemarker)
                //自定義文件名稱
                .fileName("商品資料庫表結構").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()
                //指定生成邏輯、當存在指定表、指定表前綴、指定表後綴時，將生成指定表，其餘表不生成、並跳過忽略表配置
                //根據名稱指定表生成
                .designatedTableName(new ArrayList<>())
                //根據表前綴生成
                .designatedTablePrefix(new ArrayList<>())
                //根據表後綴生成
                .designatedTableSuffix(new ArrayList<>())
                //忽略表名
                .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();
    }
}

2、Maven插件方式

pom文件添加插件

<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>

運行插件

運行成功後，我們看到在當前項目中已經存在了，資料庫文檔。

補充

有關screw工具的補充，可以查看源碼: //gitee.com/leshalv/screw。

自己也把該篇文章的演示程式碼放到了github上，具體地址: //github.com/yudiandemingzi/spring-boot-study

Tags: 【Study】-- Tool