Effortlessly Generate Database Schema Docs and Java Entities with Screw

When documenting APIs we often rely on tools like Swagger, but database schema documentation still requires manual effort. Screw is a lightweight, easy‑to‑use generator that creates database schema documents for MySQL, Oracle, PostgreSQL and other relational databases.

Screw Introduction

Screw’s source code is available at https://github.com/pingfangushi/screw . It can output documentation in HTML, Word, and Markdown formats.

Quick Start with Java Code

Screw supports two ways of generating documentation: via Java code or a Maven plugin.

Using Java Code

Create a sample project (e.g., lab-70-db-doc-screw-01) and add the screw-core dependency along with database drivers.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <parent>
    <artifactId>lab-70-db-doc</artifactId>
    <groupId>cn.iocoder.springboot.labs</groupId>
    <version>1.0-SNAPSHOT</version>
  </parent>
  <modelVersion>4.0.0</modelVersion>
  <artifactId>lab-70-db-doc-screw-01</artifactId>
  <dependencies>
    <!-- screw core -->
    <dependency>
      <groupId>cn.smallbun.screw</groupId>
      <artifactId>screw-core</artifactId>
      <version>1.0.5</version>
    </dependency>
    <!-- database drivers -->
    <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>
</project>

Write a ScrewMain class that builds a Configuration, creates a data source, engine config and process config, then executes DocumentationExecute to generate the docs.

public class ScrewMain {
    private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
    private static final String DB_NAME = "mall_system";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";
    private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
    private static final EngineFileType FILE_OUTPUT_TYPE = EngineFileType.HTML;
    private static final String DOC_FILE_NAME = "数据库文档";
    private static final String DOC_VERSION = "1.0.0";
    private static final String DOC_DESCRIPTION = "文档描述";

    public static void main(String[] args) {
        Configuration config = Configuration.builder()
            .version(DOC_VERSION)
            .description(DOC_DESCRIPTION)
            .dataSource(buildDataSource())
            .engineConfig(buildEngineConfig())
            .produceConfig(buildProcessConfig())
            .build();
        new DocumentationExecute(config).execute();
    }

    private static DataSource buildDataSource() {
        HikariConfig hikariConfig = new HikariConfig();
        hikariConfig.setDriverClassName("com.mysql.cj.jdbc.Driver");
        hikariConfig.setJdbcUrl(DB_URL + "/" + DB_NAME);
        hikariConfig.setUsername(DB_USERNAME);
        hikariConfig.setPassword(DB_PASSWORD);
        hikariConfig.addDataSourceProperty("useInformationSchema", "true");
        return new HikariDataSource(hikariConfig);
    }

    private static EngineConfig buildEngineConfig() {
        return EngineConfig.builder()
            .fileOutputDir(FILE_OUTPUT_DIR)
            .openOutputDir(false)
            .fileType(FILE_OUTPUT_TYPE)
            .produceType(EngineTemplateType.freemarker)
            .fileName(DOC_FILE_NAME)
            .build();
    }

    private static ProcessConfig buildProcessConfig() {
        return ProcessConfig.builder()
            .designatedTableName(Collections.emptyList())
            .designatedTablePrefix(Collections.emptyList())
            .designatedTableSuffix(Collections.emptyList())
            .ignoreTableName(Arrays.asList("test_user", "test_group"))
            .ignoreTablePrefix(Collections.singletonList("test_"))
            .ignoreTableSuffix(Collections.singletonList("_test"))
            .build();
    }
}

Running the program generates an HTML document (see screenshot).

Using Maven Plugin

Create another sample project (e.g., lab-70-db-doc-screw-02) and add the screw-maven-plugin to the build/plugins section.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>cn.smallbun.screw</groupId>
        <artifactId>screw-maven-plugin</artifactId>
        <version>1.0.5</version>
        <configuration>
          <driverClassName>com.mysql.cj.jdbc.Driver</driverClassName>
          <jdbcUrl>jdbc:mysql://400-infra.server.iocoder.cn:3306/mall_system</jdbcUrl>
          <username>root</username>
          <password>3WLiVUBEwTbvAfsh</password>
          <fileType>HTML</fileType>
          <title>数据库文档</title>
          <fileName>测试文档名称</fileName>
          <description>数据库文档生成</description>
          <openOutputDir>false</openOutputDir>
          <produceType>freemarker</produceType>
        </configuration>
        <executions>
          <execution>
            <phase>compile</phase>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Running mvn compile creates the documentation under the doc directory (see screenshot).

Generating Java Entity Classes

Screw can also generate Java POJOs based on the table structure via the screw-extension module.

Dependency

Add both screw-core and screw-extension to the project’s pom.xml.

<dependencies>
  <dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-core</artifactId>
    <version>1.0.5</version>
  </dependency>
  <dependency>
    <groupId>cn.smallbun.screw</groupId>
    <artifactId>screw-extension</artifactId>
    <version>1.0.5</version>
  </dependency>
</dependencies>

POJO Generation Code

Use PojoConfiguration and PojoExecute to generate entity classes.

public class ScrewMain {
    private static final String DB_URL = "jdbc:mysql://400-infra.server.iocoder.cn:3306";
    private static final String DB_NAME = "mall_system";
    private static final String DB_USERNAME = "root";
    private static final String DB_PASSWORD = "3WLiVUBEwTbvAfsh";
    private static final String FILE_OUTPUT_DIR = "/Users/yunai/screw_test";
    private static final String JAVA_CLASS_PACKAGE = "cn.iocoder.dataobject";

    public static void main(String[] args) {
        PojoConfiguration config = PojoConfiguration.builder()
            .path(FILE_OUTPUT_DIR)
            .packageName(JAVA_CLASS_PACKAGE)
            .nameStrategy(new HumpNameStrategy())
            .useLombok(false)
            .dataSource(buildDataSource())
            .processConfig(buildProcessConfig())
            .build();
        new PojoExecute(config).execute();
    }
    // buildDataSource() and buildProcessConfig() are similar to the previous example
}

After execution, Java entity files are generated (see screenshot).

Note: screw-extension is still in early development and is not published to Maven Central; you need to clone and build it locally.

Summary

Screw can generate database schema documentation in HTML, Word, and Markdown.

It can also generate Java entity classes via the screw-extension module.

Both Java‑code and Maven‑plugin approaches are supported, making it easy to integrate into existing Spring Boot projects.