Automate Database Documentation in SpringBoot with Screw: A Complete Guide

Environment: SpringBoot 3.2.5 + Screw 1.0.5.

1. Introduction

Maintaining a database table‑structure document is crucial for:

Clear data model : provides a visual view of tables, fields, and relationships for developers, testers, and operations.

Communication and collaboration : serves as a reference when discussing schema changes.

Change management : records additions, modifications, or deletions of columns and tables, explaining reasons and impacts.

Onboarding : helps new team members quickly understand the data model.

Maintainability : enables fast issue location and resolution.

Screw is a lightweight tool that automatically generates database schema documents in multiple formats, saving time and reducing errors.

2. Screw Overview

2.1 Features

Simple, lightweight, well‑designed.

Supports many databases.

Produces HTML, Word, and Markdown files.

Highly extensible with custom templates.

2.2 Supported Databases

MySQL, MariaDB, TiDB, Oracle, SqlServer, PostgreSQL, Cache DB (2016).

2.3 Supported Document Types

HTML

Word

Markdown

Example directory and table screenshots:

3. Practical Example

3.1 Add Screw Dependency

<code>&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.5&lt;/version&gt;
&lt;/dependency&gt;</code>

3.2 Define Screw Configuration Properties

<code>public class ScrewProperties {
  /** Database script version */
  private String version;
  /** Title */
  private String title;
  /** Description */
  private String desc;
  /** Organization */
  private String org;
  /** Organization URL */
  private String orgUrl;
  /** Enable flag */
  private boolean enabled = false;
  private boolean autoGen = false;
  private ScrewConfig config = new ScrewConfig();
  private TableConfig tables = new TableConfig();

  public static class TableConfig {
    private List<String> designatedTables = new ArrayList<>();
    private List<String> designatedTablePrefixs = new ArrayList<>();
    private List<String> designatedTableSuffixs = new ArrayList<>();
    private List<String> ignoreTables = new ArrayList<>();
    private List<String> ignoreTablePrefixs = new ArrayList<>();
    private List<String> ignoreTableSuffixs = new ArrayList<>();
  }

  public static class ScrewConfig {
    private String fileOutputDir;
    private boolean openOutputDir = true;
    private EngineFileType fileType = EngineFileType.HTML;
    private EngineTemplateType produceType = EngineTemplateType.freemarker;
    private String fileName = "数据库设计文档";
  }
}</code>

3.3 Generate Documentation Component

<code>@Component
public class DatabaseDocComponent {
  private final DataSource dataSource;
  private final ScrewProperties screwProperties;

  public DatabaseDocComponent(DataSource dataSource, ScrewProperties screwProperties) {
    this.dataSource = dataSource;
    this.screwProperties = screwProperties;
  }

  public void genDocument() {
    EngineConfig engineConfig = EngineConfig.builder()
      .fileOutputDir(screwProperties.getConfig().getFileOutputDir())
      .openOutputDir(screwProperties.getConfig().isOpenOutputDir())
      .fileType(screwProperties.getConfig().getFileType())
      .produceType(screwProperties.getConfig().getProduceType())
      .fileName(screwProperties.getConfig().getFileName())
      .build();

    ProcessConfig processConfig = ProcessConfig.builder()
      .designatedTableName(screwProperties.getTables().getDesignatedTables())
      .designatedTablePrefix(screwProperties.getTables().getDesignatedTablePrefixs())
      .designatedTableSuffix(screwProperties.getTables().getDesignatedTableSuffixs())
      .ignoreTableName(screwProperties.getTables().getIgnoreTables())
      .ignoreTablePrefix(screwProperties.getTables().getIgnoreTablePrefixs())
      .ignoreTableSuffix(screwProperties.getTables().getIgnoreTableSuffixs())
      .build();

    Configuration config = Configuration.builder()
      .version(screwProperties.getVersion())
      .title(screwProperties.getTitle())
      .description(screwProperties.getDesc())
      .organization(screwProperties.getOrg())
      .organizationUrl(screwProperties.getOrgUrl())
      .dataSource(dataSource)
      .engineConfig(engineConfig)
      .produceConfig(processConfig)
      .build();

    new DocumentationExecute(config).execute();
  }
}</code>

3.4 Test Document Generation

<code>@SpringBootTest
public class ScrewTest {
  @Resource
  private DatabaseDocComponent doc;

  @Test
  public void testGenDoc() {
    doc.genDocument();
  }
}</code>

The generated documentation appears in the configured output directory, as shown in the screenshots below: