Docs/init integrations (#348)

* 📝 integrations mv READMEs to vitepress * 📝 integrations fix links * 📝 integrations describe modules and graph * 🐛 docs integrations fix broken links * 📝 integrations additional modules text * 📝 integrations graph description * 📝 integrations fix typo * ✏️ docs fix cosys sidebar link case * ✏️ docs cosys add s3 link * ✏️ docs link s3 mentions * ✏️ docs integrations index update address description * Apply suggestions from code review Co-authored-by: Tobias Stadler <[email protected]> * Apply suggestions from code review Co-authored-by: Tobias Stadler <[email protected]> * ✏️ docs integrations index update description * ✏️ docs integrations update s3 client starter reference * ✏️ docs integrations dms rest-api description * ✏️ docs integrations mail rm s3 properties reference * ✏️ docs integrations s3 update service reference * ✏️ docs integrations implement review * ✏️ docs integrations implement review * ✏️ docs integrations implement review * ✏️ docs integrations implement review --------- Co-authored-by: Tobias Stadler <[email protected]>
it-at-m · Jan 17, 2025 · f5e339c · f5e339c
1 parent 9a68bd6
commit f5e339c
Show file tree

Hide file tree

Showing 9 changed files with 245 additions and 150 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -34,7 +34,13 @@ const vitepressConfig = defineConfig({
       {
         text: "Integrations",
         link: "/integrations",
-        items: [{ text: "S3", link: "/integrations/s3" }],
+        items: [
+          { text: "S3", link: "/integrations/s3" },
+          { text: "Address", link: "/integrations/address" },
+          { text: "CoSys", link: "/integrations/cosys" },
+          { text: "DMS", link: "/integrations/dms" },
+          { text: "E-Mail", link: "/integrations/email" },
+        ],
       },
     ],
     outline: {

diff --git a/...ons/refarch-address-integration/README.md → docs/integrations/address.md b/...ons/refarch-address-integration/README.md → docs/integrations/address.md
@@ -1,7 +1,11 @@
-# RefArch address integration
+# Address Integration
 
 Integration for reading, searching and validating addresses via the LHM address service.
 
+## Modules
+
+The modules follow the [default naming convention](./index.md#naming-conventions).
+
 ## Usage
 
 ```xml

diff --git a/...tions/refarch-cosys-integration/README.md → docs/integrations/cosys.md b/...tions/refarch-cosys-integration/README.md → docs/integrations/cosys.md
@@ -1,6 +1,20 @@
-# RefArch CoSys integration
+# CoSys Integration
 
-Integration for creating documents with [coSys](https://www.cib.de/cosys/). Uses s3-integration for file handling.
+Integration for creating documents with [coSys](https://www.cib.de/cosys/). Uses [s3-integration](./s3.md) for file handling.
+
+## Modules
+
+The modules follow the [default naming convention](./index.md#naming-conventions).
+
+### Dependency graph
+
+The following graph shows the relationships between the various modules and how they interact and rely on each other.
+
+```mermaid
+flowchart RL
+    example --> starter --> core --> client
+    core --> s3-client
+```
 
 ## Usage
 
@@ -15,7 +29,8 @@ Integration for creating documents with [coSys](https://www.cib.de/cosys/). Uses
 </dependencies>
 ```
 
-and a [s3-integration starter](../refarch-s3-integration/README.md#usage).
+Additionally, a specific `s3-integration-*-client-starter` is required as dependency, because S3 is used for file handling.
+See [according documentation](./s3.md#usage).
 
 ## Configuration
 

diff --git a/...rations/refarch-dms-integration/README.md → docs/integrations/dms.md b/...rations/refarch-dms-integration/README.md → docs/integrations/dms.md
@@ -1,7 +1,28 @@
-# RefArch DMS integration
+# DMS Integration
 
-Integration for CRUD operations on a dms system in specific fabasoft. Uses
-s3-integration for file handling.
+Integration for CRUD operations on a dms system in specific fabasoft. Uses [s3-integration](./s3.md) for file handling.
+
+## Modules
+
+The modules follow the [default naming convention](./index.md#naming-conventions).
+
+Besides the default modules we provide the additional ones:
+
+- `soap-api`: Interface for accessing the SOAP-API of the underlying service.
+- `soap-mock`: Mock for testing purposes of soap-api.
+- `rest-api`: Interface for accessing the REST-API of the underlying service. Alternative to soap-api but can't currently be used as drop-in-replacement.
+
+### Dependency graph
+
+The following graph shows the relationships between the various modules and how they interact and rely on each other.
+
+```mermaid
+flowchart RL
+    starter --> core --> fabasoft-soap-api
+    core --> s3-client
+    fabasoft-soap-mock-service --> fabasoft-soap-mock --> fabasoft-soap-api
+    fabasoft-rest-api
+```
 
 ## Usage
 
@@ -16,7 +37,8 @@ s3-integration for file handling.
 </dependencies>
 ```
 
-and a [s3-integration starter](../refarch-s3-integration/README.md#usage).
+Additionally, a specific `s3-integration-*-client-starter` is required as dependency, because S3 is used for file handling.
+See [according documentation](./s3.md#usage).
 
 ## Configuration
 

diff --git a/...tions/refarch-email-integration/README.md → docs/integrations/email.md b/...tions/refarch-email-integration/README.md → docs/integrations/email.md
@@ -1,7 +1,30 @@
-# RefArch email integration
+# Email Integration
 
-Integration for sending text and html emails with attachments. Uses [s3-integration](../refarch-s3-integration) for file
-handling.
+Integration for sending text and HTML mails with attachments. Uses [s3-integration](./s3.md) for file handling.
+
+## Modules
+
+The modules follow the [default naming convention](./index.md#naming-conventions).
+
+Besides the default modules we provide the additional ones:
+
+- `email-api`: Legacy module containing core email functionality. This module will be merged into the core module in future releases and should not be used in new implementations.
+- `rest-example`: Example which uses s3-rest-client.
+- `java-example`: Example which uses s3-java-client.
+
+### Dependency graph
+
+The following graph shows the relationships between the various modules and how they interact and rely on each other.
+
+```mermaid
+flowchart RL
+    starter --> core --> api-starter --> api
+    core --> s3-client
+    rest-example --> starter
+    rest-example --> s3-rest-client-starter
+    java-example --> starter
+    java-example --> s3-java-client-starter
+```
 
 ## Usage
 
@@ -16,7 +39,8 @@ handling.
 </dependencies>
 ```
 
-and a [s3-integration starter](../refarch-s3-integration/README.md#usage).
+Additionally, a specific `s3-integration-*-client-starter` is required as dependency, because S3 is used for file handling.
+See [according documentation](./s3.md#usage).
 
 ## Configuration
 
@@ -30,5 +54,3 @@ and a [s3-integration starter](../refarch-s3-integration/README.md#usage).
 | `spring.mail.password`                  | Password of smtp server.                          |                        |
 | `refarch.mail.from-address`             | Default from address used when sending mails.     | `[email protected]`     |
 | `refarch.mail.default-reply-to-address` | Default reply to address used when sending mails. | `[email protected]` |
-
-In addition, properties of selected [s3-integration starter](../refarch-s3-integration/README.md#usage).
diff --git a/docs/integrations/index.md b/docs/integrations/index.md
@@ -1 +1,35 @@
 # Integrations
+
+Integrations are ready to use implementations for accessing often used services in own applications without re-implementing the same logic. 
+These enable reduced coding effort and maintenance as well as standardized programming interfaces.
+
+## Integrations
+
+- [s3-integration](./s3.md): For CRUD operations on a S3 storage. Also used for file handling
+  in other integrations.
+- [email-integration](./email.md): For sending text and HTML emails with attachments. Uses
+  s3-integration for file handling.
+- [dms-integration](./dms.md): For CRUD operations on a DMS system in specific fabasoft. Uses
+  s3-integration for file handling.
+- [cosys-integration](./cosys.md): For creating documents with coSys. Uses
+  s3-integration for file handling.
+- [address-integration](./address.md): For reading, searching and validating addresses via the LHM address service.
+
+## Naming conventions
+
+The different submodules of integrations follow following naming conventions:
+
+- `*-client`: Interface for accessing the API of the underlying service.
+- `*-core`: Implementation of the base functionality of the integration in hexagonal architecture.
+- `*-starter`: Provides Beans of core services.
+- `*-service`: A Spring application using the starter. It is provided as container image and should not be used as dependency.
+- `*-example`: An example Spring application for testing and reference. It should not be used as dependency or in real environments.
+
+### Dependency graph
+
+The following graph shows the relationships between the various modules and how they interact and rely on each other.
+
+```mermaid
+flowchart RL
+    service --> starter --> core --> client
+```
diff --git a/docs/integrations/s3.md b/docs/integrations/s3.md
@@ -1 +1,127 @@
-# S3-Integration
+# S3 Integration
+
+Integration for CRUD operations on a S3 storage. Also used for file handling in other integrations.
+
+## Modules
+
+The S3 integration follows the [default naming conventions](./index.md#naming-conventions).
+
+Beside the default integration it contains different client libraries for accessing the integration. The client
+libraries are especially provided for usage in other integrations.
+
+- REST: The REST client uses the REST endpoints of the `s3-rest-service` module to manage data in S3.
+- Java: The Java client directly uses the in ports of the `s3-core` module.
+
+### Dependency graph
+
+The following graph shows the relationships between the various modules and how they interact and rely on each other.
+
+```mermaid
+flowchart RL
+    rest-service --> rest-starter --> rest-core --> core
+    rest-starter --> starter --> core
+    
+    java-client-starter --> java-client --> client-core
+    java-client --> core
+    java-client-starter --> starter
+    rest-client-starter --> rest-client --> client-core
+    rest-client -.REST.-> rest-service
+```
+
+## Usage
+
+```xml
+
+<dependencies>
+    <!-- REST -->
+    <!-- requires running instance of s3-rest-service -->
+    <dependency>
+        <groupId>de.muenchen.refarch</groupId>
+        <artifactId>refarch-s3-integration-rest-starter</artifactId>
+        <version>...</version>
+    </dependency>
+    <!-- or Java -->
+    <dependency>
+        <groupId>de.muenchen.refarch</groupId>
+        <artifactId>refarch-s3-integration-java-starter</artifactId>
+        <version>...</version>
+    </dependency>
+</dependencies>
+```
+
+## Configuration
+
+Following are the properties to configure the different modules. Some of them are custom defined and others are synonyms
+for spring package properties.
+Whether a property is an alias can be checked in the corresponding `application.yml` of each module.
+
+### s3-integration-rest-service
+
+| Property                                        | Description                       | Example          |
+|-------------------------------------------------|-----------------------------------|------------------|
+| `refarch.s3.url`                                | URL of S3 endpoint to connect to. | `s3.example.com` |
+| `refarch.s3.bucket-name`                        | Name of the bucket to connect to. | `refarch-bucket` |
+| `refarch.s3.access-key`                         | Access key to use for connection. |                  |
+| `refarch.s3.secret-key`                         | Secret key to use for connection. |                  |
+| `refarch.s3.initial-connection-test` (optional) | Test connection to S3 at startup.  | `true` (default) |
+
+For authenticating the different endpoints OAuth 2.0 authentication needs to be configured.
+See below example or the [according Spring documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html#oauth2-resource-server).
+
+```yml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://sso.example.com/auth/realms/refarch
+security:
+  oauth2:
+    resource:
+      user-info-uri: ${spring.security.oauth2.resourceserver.jwt.issuer-uri}/protocol/openid-connect/userinfo
+```
+
+### s3-integration-java-client-starter
+
+| Property                                                   | Description                                           | Example                  |
+|------------------------------------------------------------|-------------------------------------------------------|--------------------------|
+| `refarch.s3.client.max-file-size` (optional)               | Single file limit for up- or downloading in byte.     | `10MB`                   |
+| `refarch.s3.client.max-batch-size` (optional)              | Limit for up- or downloading a list of files in byte. | `100MB`                  |
+| `refarch.s3.client.supported-file-extensions.*` (optional) | Map of allowed file extensions for up- and download.  | `pdf: "application/pdf"` |
+
+### s3-integration-rest-client-starter
+
+All properties of [s3-integration-java-client-starter](#s3-integration-java-client-starter) and following:
+
+| Property                                 | Description                                                                | Example                                       |
+|------------------------------------------|----------------------------------------------------------------------------|-----------------------------------------------|
+| `refarch.s3.client.document-storage-url` | URL to the RefArch S3 integration service.                                 | `http://s3-integration-service:8080`          |
+| `refarch.s3.client.enable-security`      | Switch to enable or disable OAuth 2.0 authentication against S3 service.      | `true`                                        |
+
+For authentication against the `s3-service` a OAuth 2.0 registration with the name `s3` needs to be provided.
+See following example or the [according Spring documentation](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html#oauth2-client).
+
+```yml
+spring:
+  security:
+    oauth2:
+      client:
+        provider:
+          sso:
+            issuer-uri: https://sso.example.com/auth/realms/refarch
+            user-info-uri: ${spring.security.oauth2.client.provider.sso.issuer-uri}/protocol/openid-connect/userinfo
+            jwk-set-uri: ${spring.security.oauth2.client.provider.sso.issuer-uri}/protocol/openid-connect/certs
+            # used for RequestResponseLoggingFilter in s3-rest-service
+            # only required if filter is explicitly enabled
+            user-name-attribute: user_name
+        registration:
+          s3:
+            provider: sso
+            authorization-grant-type: client_credentials
+            client-id: refarch_client
+            client-secret: client_secret_123
+            # profile required for username used in s3-rest-service RequestResponseLoggingFilter
+            # openid required for user info endpoint used in s3-rest-service JwtUserInfoAuthenticationConverter
+            # both scopes are only required if the according functions are explicitly used
+            scope: profile, openid
+```
diff --git a/refarch-integrations/README.md b/refarch-integrations/README.md