Documented company/03-api.

Author: pme123

00-docs/src/docs/company/02-bpmn.md

@@ -2,7 +2,7 @@
 
 Use this to add Company specific BPMN stuff like business objects used in all projects.
 
-The following structure is generated by `../helperCompany.scala init`:
+The following structure is generated by `./helperCompany.scala init`:
 
 ```bash
 02-bpmn/src

00-docs/src/docs/company/03-api.md

@@ -1,7 +1,7 @@
 # 03-api
 Use this to add Company specific API stuff like the configuration of the projects within the Company.
 
-The following structure is generated by `../helperCompany.scala init`:
+The following structure is generated by `./helperCompany.scala init`:
 
 ```bash
 03-api/src
@@ -15,38 +15,193 @@ The following structure is generated by `../helperCompany.scala init`:
 
 The Company's base class to generate the API documentation and API Clients for Postman.
 
-Example:
+Example (generated by `./helperCompany.scala init`):
 
-```scala mdoc
+```scala
 import camundala.api.*
 
 trait CompanyApiCreator extends ApiCreator, ApiDsl, CamundaPostmanApiCreator:
 
     // override the config if needed
     protected def apiConfig: ApiConfig = CompanyApiCreator.apiConfig
-    
-    lazy val companyDescr = ??? //TODO Add your Company Description!
+
+    lazy val companyProjectVersion = BuildInfo.version
 
 object CompanyApiCreator:
-    lazy val apiConfig = ApiConfig(companyId = "mycompany")
+    lazy val apiConfig = ApiConfig(companyName = "mycompany")
 end CompanyApiCreator
 ```
 
 ## ApiConfig
-You can define the project structure.
+You can customize the API Configuration.
+
+Here an example:
+
+```scala mdoc
+import camundala.api.ApiConfig
+
+lazy val apiConfig: ApiConfig =
+  ApiConfig("mycompany")
+    .withTenantId("mycompany")
+    .withDocBaseUrl(s"http://mycompany.ch/bpmnDocs")
+    .withJiraUrls("COM" -> "https://issue.mycompany.ch/browse")  
+```
+
+## Default ApiConfig
+This is the default Configuration:
+```scala
+// your company name like 'mycompany'
+companyName: String,
+// define tenant if you have one - used for the Postman OpenApi
+tenantId: Option[String] = None,
+// contact email / phone, if there are questions
+contact: Option[Contact] = None,
+// REST endpoint (for testing API)
+endpoint: String = "http://localhost:8080/engine-rest",
+// Base Path of your project (if changed - all doc paths will be adjusted)
+basePath: os.Path = os.pwd,
+// If you work with JIRA, you can add matchers that will create automatically URLs to JIRA Tasks
+jiraUrls: Map[String, String] = Map.empty,
+// Configure your project setup
+projectsConfig: ProjectsConfig = ProjectsConfig(),
+// Configure your template generation
+modelerTemplateConfig: ModelerTemplateConfig = ModelerTemplateConfig(),
+// The URL of your published documentations
+// s"http://myCompany/bpmnDocs"
+docBaseUrl: Option[String] = None,
+// Path, where the Git Projects are cloned - for dependency check.
+// the default is for the structure: dev-myCompany/projects/myProject
+tempGitDir: os.Path = os.pwd / os.up / os.up / "git-temp"
+```
+
+## ProjectsConfig
+You can configure your projects.
 
 Here an example:
 
 ```scala mdoc
 import camundala.api.*
 
-lazy val apiConfig = 
-  ApiConfig(companyId = "mycompany")
-  
+lazy val projectsConfig = ProjectsConfig(
+  // Path to your ApiProjectConf - default is os.pwd / PROJECT.conf
+  projectConfPath = os.rel / "src" / "main" / "resources" / "myproject.conf",
+  // grouped configs per GitRepos - so it is possible to use projects from different Repos
+  perGitRepoConfigs = Seq(myCompanyGitRepoConfig)
+)
+
+lazy val myCompanyGitRepoConfig = ProjectsPerGitRepoConfig(
+  // Base URL for the Git Repos
+  // The pattern must be $cloneBaseUrl/$projectName.git
+  cloneBaseUrl = "ssh://git@mycompany.com:2222/myrepo",
+  // Definition of the projects
+  projects = myProjects
+)
+
+lazy val myProjects = Seq(`mycompany-services`, `mycompany-finances`, `mycompany-employees`)
+
+lazy val `mycompany-services` = ProjectConfig(
+  // Name of the project
+  name = "mycompany-services",
+  // you can group your projects - for better overview
+  group =  services,
+  // the color of your project - for better overview and visualization in the BPMN diagrams
+  color = "blue"
+)
+
+lazy val `mycompany-finances` = ???
+lazy val `mycompany-employees` = ???
+lazy val services = ProjectGroup(
+  name = "services",
+  // line color
+  color = "purple",
+  fill = "#ddd"
+)
+
+```
+
+@:callout(info)
+All other information is taken automatically from the _ApiProjectConf_.
+@:@
+
+## Standard Features:
+
+With the API Creator you get a lot of features out of the box.
+
+#### README
+If you have a read me in your base path (`config.basePath / "README.md`),
+we integrate it automatically in the documentation - as a visible part.
+
+#### CHANGELOG
+If you have a change log in your base path (`config.basePath / "CHANGELOG.md`),
+we integrate it automatically in the documentation - as a collapsed part.
+
+#### General Variables
+General variables that are supported in any Process- and/or ExternalTask-Worker are documented - in a collapsed part.
+By default, the following Variables are supported:
+
+```scala mdoc
+enum InputParams:
+  // mocking
+  case servicesMocked
+  case mockedWorkers
+  case outputMock
+  case outputServiceMock
+  // mapping
+  case manualOutMapping
+  case outputVariables
+  case handledErrors
+  case regexHandledErrors
+  // authorization
+  case impersonateUserId
+  // ..
+end InputParams
+```
+That expects that your implementation can handle these variables.
+
+@:callout(info)
+If you are using our Workers they are supported out of the box!
+@:@
+
+If you only want to support some of them, you can override them:
+
+```scala
+  override def supportedVariables: Seq[InputParams] = Seq(
+    servicesMocked,
+    outputMock,
+    outputServiceMock,
+    handledErrors,
+    regexHandledErrors,
+    impersonateUserId
+  )
+```
 
+#### Jira Tickets
+We replace configured JIRA Ticket pattern with its URL.
+
+Configuration:
+```scala
+  override protected def apiConfig: ApiConfig =
+    super.apiConfig
+      .withJiraUrls(JIRA_PROJECT -> JIRA_URL)  
 ```
 
+- JIRA_PROJECT: The shortcut for the JIRA Project (prefix of jira ticket number).
+- JIRA_URL: The base URL to browse JIRA tickets, e.g. `https://issue.mycompany.ch/browse`.
+
+Now in the Change Log all occurrences of the regex `JIRA_PROJECT-(\\d+)` (-> `JIRA_TICKET`)
+will be replaced with `[JIRA_TICKET]($url/JIRA_TICKET)`.
+In the generated documentation this is a link to the according Jira ticket.
+
+#### BPMN diagrams
+BPMN- and DMN diagrams are integrated in the documentation.
+
+They are referenced in the OpenApi.html and can be opened directly from there. 
+There are 3 ways:
+
+1. As an image in the documentation
+2. As a link to download the BPMN-/ DMN-diagram
+3. As SVG image to show the diagram in the browser (you can zoom in and out)
 
 @:callout(info)
-Documentation of `companyDescr` will be in every API documentation. So ones per project.
+This is only working if you upload your BPMN- and DMN-diagrams to a Web server (via WebDAV).
 @:@

00-docs/src/docs/company/04-helper.md

@@ -1 +1,20 @@
-# 04-helper
+# 04-helper
+
+### CompanyDevHelper
+With the `CompanyDevHelper` you can customize  _Camundala_ for your Company:
+
+```scala mdoc
+import camundala.api.*
+import camundala.helper.dev.DevHelper
+import camundala.helper.util.*
+
+case class CompanyDevHelper(projectName: String, subProjects: Seq[String] = Seq.empty)
+    extends DevHelper:
+
+  lazy val apiConfig: ApiConfig = ApiConfig("mycompany")//.withTenantId("mycompany")...
+
+  def deployConfig: Option[DeployConfig] = ???
+  def devConfig: DevConfig = ???
+  def dockerConfig: DockerConfig = ???
+
+```

00-docs/src/docs/company/development.md

@@ -10,11 +10,12 @@ chmod +x helper.scala
 ```
 
 @:callout(info)
-To update this project, use `../helperCompany init` - see  [Init Company].
+To update this project, use `cd ..` and then `./helperCompany init` - see  [Init Company].
 @:@
 
 ## publish
-
+TODO
 ## prepareDocs
-
+TODO
 ## publishDocs
+TODO