Generate Database Documentation with Screw and Maven in Minutes

Background

Our department needed a unified order platform and had to document hundreds of tables across multiple business lines. Manually handling each table was tedious, so we searched GitHub for a tool and discovered

screw

, which can generate database documentation automatically.

Supported Databases

MySQL

MariaDB

TiDB

Oracle

SqlServer

PostgreSQL

Cache DB

Configuration

1. pom.xml dependencies

<code>&lt;!-- screw core --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;cn.smallbun.screw&lt;/groupId&gt;
    &lt;artifactId&gt;screw-core&lt;/artifactId&gt;
    &lt;version&gt;1.0.3&lt;/version&gt;
&lt;/dependency&gt;

&lt;!-- HikariCP --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;com.zaxxer&lt;/groupId&gt;
    &lt;artifactId&gt;HikariCP&lt;/artifactId&gt;
    &lt;version&gt;3.4.5&lt;/version&gt;
&lt;/dependency&gt;

&lt;!-- mysql driver --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;mysql&lt;/groupId&gt;
    &lt;artifactId&gt;mysql-connector-java&lt;/artifactId&gt;
    &lt;version&gt;8.0.20&lt;/version&gt;
&lt;/dependency&gt;</code>

2. Data source configuration

<code>spring.datasource.url=jdbc:mysql://45.93.1.5:3306/fire?useUnicode=true&amp;characterEncoding=UTF-8&amp;useSSL=false
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.xa.properties.useInformationSchema=true</code>

3. Screw core configuration (pom or code)

The

screw

plugin can be configured in the Maven

pom.xml

or invoked programmatically. Below is a Maven plugin example:

<code>&lt;build&gt;
    &lt;plugins&gt;
        &lt;plugin&gt;
            &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
            &lt;artifactId&gt;spring-boot-maven-plugin&lt;/artifactId&gt;
        &lt;/plugin&gt;
        &lt;plugin&gt;
            &lt;groupId&gt;cn.smallbun.screw&lt;/groupId&gt;
            &lt;artifactId&gt;screw-maven-plugin&lt;/artifactId&gt;
            &lt;version&gt;1.0.3&lt;/version&gt;
            &lt;dependencies&gt;
                &lt;!-- HikariCP --&gt;
                &lt;dependency&gt;
                    &lt;groupId&gt;com.zaxxer&lt;/groupId&gt;
                    &lt;artifactId&gt;HikariCP&lt;/artifactId&gt;
                    &lt;version&gt;3.4.5&lt;/version&gt;
                &lt;/dependency&gt;
                &lt;!-- mysql driver --&gt;
                &lt;dependency&gt;
                    &lt;groupId&gt;mysql&lt;/groupId&gt;
                    &lt;artifactId&gt;mysql-connector-java&lt;/artifactId&gt;
                    &lt;version&gt;8.0.20&lt;/version&gt;
                &lt;/dependency&gt;
            &lt;/dependencies&gt;
            &lt;configuration&gt;
                &lt;username&gt;root&lt;/username&gt;
                &lt;password&gt;123456&lt;/password&gt;
                &lt;driverClassName&gt;com.mysql.cj.jdbc.Driver&lt;/driverClassName&gt;
                &lt;jdbcUrl&gt;jdbc:mysql://41.92.6.5:3306/fire&lt;/jdbcUrl&gt;
                &lt;fileType&gt;HTML&lt;/fileType&gt;
                &lt;openOutputDir&gt;false&lt;/openOutputDir&gt;
                &lt;produceType&gt;freemarker&lt;/produceType&gt;
                &lt;description&gt;数据库文档生成&lt;/description&gt;
                &lt;version&gt;${project.version}&lt;/version&gt;
                &lt;title&gt;fire数据库文档&lt;/title&gt;
            &lt;/configuration&gt;
            &lt;executions&gt;
                &lt;execution&gt;
                    &lt;phase&gt;compile&lt;/phase&gt;
                    &lt;goals&gt;
                        &lt;goal&gt;run&lt;/goal&gt;
                    &lt;/goals&gt;
                &lt;/execution&gt;
            &lt;/executions&gt;
        &lt;/plugin&gt;
    &lt;/plugins&gt;
&lt;/build&gt;</code>

After configuration, run the Maven goal

screw

to generate the documentation.

4. Programmatic generation (SpringBootTest example)

<code>@SpringBootTest
public class ScrewApplicationTests {

    @Autowired
    ApplicationContext applicationContext;

    @Test
    void contextLoads() {
        DataSource dataSourceMysql = applicationContext.getBean(DataSource.class);
        // Engine configuration
        EngineConfig engineConfig = EngineConfig.builder()
                .fileOutputDir("D:/")
                .openOutputDir(false)
                .fileType(EngineFileType.HTML)
                .produceType(EngineTemplateType.freemarker)
                .build();
        // Documentation configuration
        Configuration config = Configuration.builder()
                .version("1.0.3")
                .description("生成文档信息描述")
                .dataSource(dataSourceMysql)
                .engineConfig(engineConfig)
                .produceConfig(getProcessConfig())
                .build();
        new DocumentationExecute(config).execute();
    }

    /**
     * Configure tables to include or ignore.
     */
    public static ProcessConfig getProcessConfig() {
        List<String> ignoreTableName = Arrays.asList("a", "test_group");
        List<String> ignorePrefix = Arrays.asList("a", "t");
        List<String> ignoreSuffix = Arrays.asList("_test", "czb_");
        return ProcessConfig.builder()
                .designatedTableName(Arrays.asList("fire_user"))
                .designatedTablePrefix(new ArrayList<>())
                .designatedTableSuffix(new ArrayList<>())
                .ignoreTableName(ignoreTableName)
                .ignoreTablePrefix(ignorePrefix)
                .ignoreTableSuffix(ignoreSuffix)
                .build();
    }
}
</code>

Document Formats

The

screw

tool can output documentation in three formats:

HTML

,

DOC

, and

MD

. Change the format by setting

fileType

in the configuration or in the pom.

<code>.fileType(EngineFileType.HTML)</code>

<code>&lt;fileType&gt;MD&lt;/fileType&gt;</code>

DOC style

HTML style

MD style

Conclusion

The Screw tool proved extremely useful, allowing us to finish the documentation task quickly and efficiently.