feat: add the uml generator

README.md

@@ -1,6 +1,6 @@
 # @openstapps/core-tools
 
-[![pipeline status](https://img.shields.io/gitlab/pipeline/openstapps/core-tools.svg?style=flat-square)](https://gitlab.com/openstapps/core-tools/commits/master) 
+[![pipeline status](https://img.shields.io/gitlab/pipeline/openstapps/core-tools.svg?style=flat-square)](https://gitlab.com/openstapps/core-tools/commits/master)
 [![npm](https://img.shields.io/npm/v/@openstapps/core-tools.svg?style=flat-square)](https://npmjs.com/package/@openstapps/core-tools)
 [![license)](https://img.shields.io/npm/l/@openstapps/core-tools.svg?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0.en.html)
 [![documentation](https://img.shields.io/badge/documentation-online-blue.svg?style=flat-square)](https://openstapps.gitlab.io/core-tools)
@@ -15,7 +15,7 @@ JSON schema files are needed for run-time validation of SC-type objects, as this
 
 The StAppsCore Validator is a tool for run-time validation of objects (determining whether a JavaScript/JSON object is a valid object of the corresponding SC-type. It consumes JSON schema files from StAppsCore as the definitions of SC-types against which are validated concrete (actual) objects (as an example SCDish object in the example below).
 
-## Installation 
+## Installation
 
 Installation of the npm package (using `npm install`) makes the tool available as an executable with the name `openstapps-core-tools`.
 
@@ -57,7 +57,7 @@ import {join} from 'path';
 
 const objectToValidate: SCDish = {
 type: SCThingType.Dish,
-// more properties
+  // more properties
 };
 
 // instantiate a new validator
@@ -127,7 +127,7 @@ Inside of a script in `package.json` or if the npm package is installed globally
 openstapps-core-tools validate lib/schema src/test/resources report.html
 ```
 
-## Generate documentation for routes 
+## Generate documentation for routes
 
 To generate a documentation for the routes use the following command.
 
@@ -142,3 +142,60 @@ To pack all the different files into two distribution files - one for definition
 ```shell
 openstapps-core-tools pack
 ```
+
+## How to use the UML generator
+
+The UML Generator generates PlantUML from the project reflection of the source files. By default it will include externals, which will take considerably longer to execute, you can disable this behaviour via an option. It can help you to visually explore the data model or document a specific part.
+
+You can either use the public PlantUML-server or start your own local instance. To build the image and run, restart or stop the container use the scripts provided in the `package.json`. 
+
+### Generating from source-files
+
+```shell
+openstapps-core-tools plantuml PATH/TO/SOURCEFILES http://PLANTUMLSERVER
+```
+
+Executing this command will generate a `.svg` file in your current working directory.
+
+Multiple options can be set to enhance the diagram. By default all additional information other than the definitions are disabled. You can use:
+
+- `--showProperties` to show all mandatory attributes of the classes and interfaces.
+- `--showOptionalProperties` to show all mandatory attributes of the classes and interfaces. `--showProperties` must be set!
+- `--showEnumValues` to show all enumeration and type (enumeration-like) values
+- `--showInheritance` to show the hierarchy of the classes and interfaces. Inherited attributes will only be shown in their parent.
+- `--showAssociations` to show all references of classes and interfaces between one another
+- `--excludeExternals` to exclude external definitions
+- `--definitions <definitons>` to show only specific definitions to reduce the output of the diagram. `<definitions>` is a comma seperated list of definitions.
+
+The best way to explore models is to enable `--showInheritance` and `--showAssociations`. Start with just one definition in your `--definition <definitions>`-list, generate the diagram, look at it, add a new definition that you have seen to your command and generate anew.
+
+#### Examples
+
+Show the class hierarchy of the whole project:
+
+```shell
+openstapps-core-tools plantuml PATH/TO/SRCDIR http://PLANTUMLSERVER --showInheritance
+```
+
+Show the dish-module:
+
+```shell
+openstapps-core-tools plantuml ../core http://localhost:8080 --showProperties --showOptionalProperties --showInheritance --showAssociations --showEnumValues --definitions SCDish,SCThingThatCanBeOfferedOffer
+```
+
+### Generating from existing file
+
+The plantuml code is persisted inside the generated filea at the very bottom. You can tweak the model by using the function to generate UML from a PlantUML-file(simple text file). Extract the code (starting from `@startuml` to `@enduml`), edit it manually and execute the function.
+
+```shell
+openstapps-core-tools plantuml-file /PATH/TO/Project.plantuml http://PLANTUMLSERVER
+```
+
+Example-File-Content of Project.plantuml 
+```
+@startuml
+interface MyClass{
+  myProperty: string
+}
+@enduml
+```