Data dictionary

.github/workflows/github-pages.yml

@@ -4,8 +4,6 @@ name: Publish Documentation Generator to GitHub Pages
 on:
   push:
     branches: [main]
-  pull_request:
-    branches: [main]
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -24,7 +22,7 @@ jobs:
           distribution: 'temurin'
 
       - name: Copy Documentation Generator Schema to site
-        run: cp -Rv documentation-generator-api/src/main/resources/documentation-schema.json site/documentation-schema.json
+        run: cp -Rv documentation-generator-api/src/main/resources/documentation-schema.json site/v1/documentation-schema.json
 
       - name: Check GitHub Pages status
         uses: crazy-max/ghaction-github-status@v3

README.md

@@ -34,6 +34,7 @@ The generators acts as plugin - Just implement `GeneratorConfiguration`.
 title: Basic idea
 ---
 flowchart TD
+  docFile["documentation file"]  
   docgen["Documentation Generator"]
   generator1["Generator 1"]
   generator1Generate[[Generates SQL-scripts]]
@@ -52,10 +53,16 @@ flowchart TD
   destination4["Destination 4"]
   csv(["CSV file"])
 
+  generatorX["Generator X"]
+  destinationX["Destination X"]
+  something(["Something else"])
+
+  docFile --> docgen
   docgen --> generator1
   docgen --> generator2
   docgen --> generator3
   docgen --> generator4
+  docgen --> generatorX
 
   generator1 --> generator1Generate
   generator1Generate --> destination1
@@ -69,6 +76,9 @@ flowchart TD
 
   generator4 --> destination4
   destination4 --> csv
+
+  generatorX --> destinationX
+  destinationX --> something
 ```
 
 ---
@@ -80,13 +90,13 @@ The documentation file or files can be yaml- or json-files.
 If you in the beginning of your file add a reference to the schema, so you IDE can validate and have code completion.
 
 ```yaml
-$schema:  https://patrickfust.github.io/documentation-generator/documentation-schema.json
+$schema:  https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json
 ```
 
 Example of a file
 
 ```yaml
-$schema:  https://patrickfust.github.io/documentation-generator/documentation-schema.json
+$schema:  https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json
 documentationTitle: My database
 schemaName: theSchema
 tables:
@@ -111,7 +121,7 @@ tables:
 or as JSON:
 ```json
 {
-    "$schema": "https://patrickfust.github.io/documentation-generator/documentation-schema.json",
+    "$schema": "https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json",
     "documentationTitle": "My database",
     "schemaName": "theSchema",
     "tables": [
@@ -172,7 +182,7 @@ You can have nested objects, you just have to specify which class name it is.
       destinationKey: MODEL_MERMAID_PLACEHOLDER
     - className: dk.fust.docgen.erdiagram.GenerateKey
       destinationKey: MODEL_MERMAID_GROUP_PLACEHOLDER
-      filter: my_group
+      filterTags: my_group
   destination:
     className: dk.fust.docgen.destination.MarkdownDestination
     file: README.md
@@ -240,18 +250,68 @@ Everything in between will be substituted.
 
 Class name: `dk.fust.docgen.confluence.destination.ConfluenceDestination`
 
-In order to use Confluence as destination, you'll need to add the module: 
-[documentation-generator-confluence](extensions/documentation-generator-confluence/)
+In order to use Confluence as destination, you'll need to add the extension `documentation-generator-confluence`.
+
+Read the documentation [here](extensions/documentation-generator-confluence)
+
+---
+
+## Table format
+
+Some generators use tables and needs a formatter to create a string representation of the table.
+The table formatter you want to use, is configured when you configure the generator.
+Example:
+```yaml
+- className: dk.fust.docgen.datadict.DataDictionaryConfiguration
+  documentationFile: data-dictionary.yml
+  tableFormatter:
+    className: dk.fust.docgen.csv.format.table.CSVTableFormatter
+  destination:
+    className: dk.fust.docgen.destination.FileDestination
+    file: data_dictionary-output.csv
+```
+
+### MarkdownTableFormatter
+
+Class name: `dk.fust.docgen.format.table.MarkdownTableFormatter`
+
+Default table formatter for most generators.
+
+Generates the table in a format that can be used i Markdown files.
+
+Use it together with [MarkdownDestination](#markdowndestination).
+
+### HTMLTableFormatter
+
+Class name: 'dk.fust.docgen.format.table.HTMLTableFormatter'
+
+| Setting      | Type                | Description                             | Default |
+|--------------|---------------------|-----------------------------------------|---------|
+| dataFields   | Map<String, String> | Data fields to be appended to the table |         |  
+| columnWidths | List<String>        | Setting column withs                    |         |  
+
+#### Example
+
+```yaml
+tableFormatter:
+  className: dk.fust.docgen.format.table.HTMLTableFormatter
+  dataFields:
+    table-width: "1800"
+  columnWidths:
+    - "255"
+    - "328"
+    - "114"
+    - "115"
+    - "149"
+    - "242"
+```
+
+### CSVTableFormatter
+
+Class name: `dk.fust.docgen.csv.format.table.CSVTableFormatter` 
 
-| Setting             | Type   | Description             | Exanple                                 |
-|---------------------|--------|-------------------------|-----------------------------------------|
-| baseUrl             | String | Base URL to Confluence. | https://xxx.atlassian.net/wiki/rest/api |
-| documentationPageId | String | Id of the parent page.  | 123456                                  |
-| spaceKey            | String | Confluence space key    | ABC                                     |
-| parentPageTitle     | String |                         | My Parent Page                          |
-| pageTitle           | String |                         | My Page                                 | 
+Read the documentation [here](extensions/documentation-generator-csv)
 
-Username and personal access token for Confluence will be promptet .
 
 ---
 

build.gradle

@@ -7,7 +7,7 @@ plugins {
 
 allprojects {
     group = 'dk.fust.docgen'
-    version = '0.0.8'
+    version = '0.0.9-SNAPSHOT'
 
     plugins.withType(JavaPlugin).whenPluginAdded {
         tasks.withType(Test).configureEach {

demos/demo-data-dictionary/documentation.yaml

@@ -1,4 +1,4 @@
-$schema:  https://patrickfust.github.io/documentation-generator/documentation-schema.json
+$schema:  https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json
 documentationTitle: My database
 schemaName: theSchema
 dataDictionary:

demos/demo-data-dictionary/gradle.properties

@@ -1 +1 @@
-documentationGeneratorVersion = 0.0.8
+documentationGeneratorVersion = 0.0.9-SNAPSHOT

demos/demo-data-lineage/documentation.yaml

@@ -1,4 +1,4 @@
-$schema:  https://patrickfust.github.io/documentation-generator/documentation-schema.json
+$schema:  https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json
 databaseName: This DB
 tables:
   - name: table_a

demos/demo-data-lineage/external-documentation.yaml

@@ -1,4 +1,4 @@
-$schema:  https://patrickfust.github.io/documentation-generator/documentation-schema.json
+$schema:  https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json
 documentationTitle: My external database
 databaseName: External DB name
 tables:

demos/demo-data-lineage/gradle.properties

@@ -1 +1 @@
-documentationGeneratorVersion = 0.0.8
+documentationGeneratorVersion = 0.0.9-SNAPSHOT

demos/demo-erdiagram/build.gradle

@@ -34,9 +34,9 @@ documentationGenerator {
 //                documentationFile: new File(projectDir, 'documentation.yaml'),
 //                umlGenerator : UMLGenerator.MERMAID, // Can be omitted because it's default
 //                generateKeys: [
-//                        // Empty filter means all groups
+//                        // Empty filterTags means all groups
 //                        new GenerateKey(destinationKey: 'MODEL_MERMAID_PLACEHOLDER'),
-//                        new GenerateKey(destinationKey: 'MODEL_MERMAID_GROUP_PLACEHOLDER', filter: 'my_group')
+//                        new GenerateKey(destinationKey: 'MODEL_MERMAID_GROUP_PLACEHOLDER', filterTags: 'my_group')
 //                ],
 //                destination: new MarkdownDestination(
 //                        file: new File('README.md'),

demos/demo-erdiagram/documentation.yaml

@@ -1,4 +1,4 @@
-$schema:  https://patrickfust.github.io/documentation-generator/documentation-schema.json
+$schema:  https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json
 documentationTitle: My database
 schemaName: theSchema
 tables:

demos/demo-erdiagram/generator-configuration.yml

@@ -6,7 +6,7 @@
       destinationKey: MODEL_MERMAID_PLACEHOLDER
     - className: dk.fust.docgen.erdiagram.GenerateKey
       destinationKey: MODEL_MERMAID_GROUP_PLACEHOLDER
-      filter: my_group
+      filterTags: my_group
   destination:
     className: dk.fust.docgen.destination.MarkdownDestination
     file: README.md

demos/demo-erdiagram/gradle.properties

@@ -1 +1 @@
-documentationGeneratorVersion = 0.0.8
+documentationGeneratorVersion = 0.0.9-SNAPSHOT

demos/demo-erdiagram/pom.xml

@@ -35,7 +35,7 @@
       <plugin>
         <groupId>dk.fust.docgen</groupId>
         <artifactId>documentation-generator-maven-plugin</artifactId>
-        <version>0.0.8</version>
+        <version>0.0.9-SNAPSHOT</version>
         <configuration>
           <documentationConfigurationFile>generator-configuration.yml</documentationConfigurationFile>
         </configuration>

demos/demo-sqlscript/documentation.yaml

@@ -1,4 +1,4 @@
-$schema:  https://patrickfust.github.io/documentation-generator/documentation-schema.json
+$schema:  https://patrickfust.github.io/documentation-generator/v1/documentation-schema.json
 documentationTitle: My database
 schemaName: theSchema
 tables:

demos/demo-sqlscript/gradle.properties

@@ -1 +1 @@
-documentationGeneratorVersion = 0.0.8
+documentationGeneratorVersion = 0.0.9-SNAPSHOT

documentation-generator-api/src/main/java/dk/fust/docgen/model/Documentation.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import dk.fust.docgen.model.datadict.DataDictionary;
+import dk.fust.docgen.model.datadict.DataDictionaryFile;
 import lombok.Data;
 
 import java.util.ArrayList;
@@ -97,18 +98,31 @@ private void mergeGenerations(Generation from, Generation to) {
     }
 
     /**
-     * Return those tables that have a tag that is equal to the filter
-     * @param filter filter to search for
+     * Returns those tables that have a tag that is equal to the filter
+     * @param filterTags filter to search for
      * @return only matching tables
      */
-    public List<Table> filterTables(String filter) {
-        if (filter != null && !filter.isEmpty()) {
+    public List<Table> filterTables(String filterTags) {
+        if (filterTags != null && !filterTags.isEmpty()) {
             // Only those with the filer
-            return tables.stream().filter(t -> t.getTags() != null && t.getTags().contains(filter)).toList();
+            return tables.stream().filter(t -> t.getTags() != null && t.getTags().contains(filterTags)).toList();
         }
         return tables;
     }
 
+    /**
+     * Returns those data dictionaries that have a tag that i equal to the filter
+     * @param filterTags filter to search for
+     * @return only matching data dictionaries
+     */
+    public List<DataDictionaryFile> filterDataDictionaryFiles(String filterTags) {
+        if (filterTags != null && !filterTags.isEmpty() && dataDictionary.getDataDictionaryFiles() != null) {
+            // Only those with the filer
+            return dataDictionary.getDataDictionaryFiles().stream().filter(t -> t.getTags() != null && t.getTags().contains(filterTags)).toList();
+        }
+        return dataDictionary.getDataDictionaryFiles();
+    }
+
     /**
      * Finds the first table with the table name
      * @param tableName searching for table name

documentation-generator-api/src/main/java/dk/fust/docgen/model/ForeignKey.java

@@ -8,7 +8,10 @@
 @Data
 public class ForeignKey {
 
+    @Description(value = "Table name the foreign key points to. Is together with columnName", required = true)
     private String tableName;
+
+    @Description(value = "Column name the foreign key points to. Is together with tableName", required = true)
     private String columnName;
 
     @Description(value = "Should the database enforce the reference?", hasDefaultBoolean = true, defaultBoolean = false)

documentation-generator-api/src/main/java/dk/fust/docgen/model/Index.java

@@ -10,8 +10,12 @@
 @Data
 public class Index {
 
+    @Description("Name of the index")
     private String name;
+
     private boolean unique = false;
+
+    @Description(value = "List of fields for the index", required = true)
     private List<String> fields;
 
 }

documentation-generator-api/src/main/java/dk/fust/docgen/model/Table.java

@@ -16,6 +16,7 @@ public class Table {
     @Description("Comment to be added to the table")
     private String comment;
 
+    @Description("List of tags that may be used in a filter")
     private List<String> tags;
 
     @Description(value = "Filename of sql-script-file to be generated. If left out, no files are generated")

documentation-generator-api/src/main/java/dk/fust/docgen/model/View.java

@@ -8,7 +8,10 @@
 @Data
 public class View {
 
+    @Description(value = "Name of the view")
     private String name;
+
+    @Description(value = "SQL that defines the view", required = true)
     private String sql;
 
 }

documentation-generator-api/src/main/java/dk/fust/docgen/model/datadict/Column.java

@@ -33,6 +33,6 @@ public class Column {
     @Description("Maximum value of the content")
     private Long maximumValue;
 
-    @Description(value = "Is this column a part of the unique key?", defaultBoolean = false)
-    private Boolean unique = false;
+    @Description(value = "Is this column a part of the unique key?")
+    private String keys;
 }

documentation-generator-api/src/main/java/dk/fust/docgen/model/datadict/DataDictionaryFile.java

@@ -17,6 +17,13 @@ public class DataDictionaryFile {
     @Description(value = "Data dictionary version", required = true)
     private String version;
 
+    @Description("Description of the file")
+    private String fileDescription;
+
     @Description(value = "The files columns", required = true)
     private List<Column> columns;
+
+    @Description("List of tags that may be used in a filter")
+    private List<String> tags;
+
 }