Documenting company bpmn / api.

Author: pme123

.scalafmt.conf

@@ -7,6 +7,8 @@ assumeStandardLibraryStripMargin = true
 binPack.literalsExclude = ["Term.Name"]
 
 maxColumn = 100 // For my wide 30" display.
+# align arrows in for comprehensions
+align.preset = most
 
 newlines.source = keep
 rewrite.scala3.convertToNewSyntax = true

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

@@ -1 +1,42 @@
-# 02-bpmn
+# 02-bpmn
+
+Use this to add Company specific BPMN stuff like business objects used in all projects.
+
+The following structure is generated by `../helperCompany.scala init`:
+
+```bash
+02-bpmn/src
+         | main/resources
+         | main/scala/company/bpmn
+         |                     | CompanyBpmnDsl.scala          
+         | test/scala/company/bpmn       
+```
+
+## CompanyBpmnDsl
+
+Provide some Company specific things for the BPMN DSL, like additional Documentation, like Links to Specifications.
+
+Example:
+
+```scala mdoc
+import camundala.bpmn.BpmnDsl
+
+trait CompanyBpmnDsl extends BpmnDsl:
+
+  def postmanRef: Option[String] = None
+  def specPage: Option[String] = None
+
+  override def companyDescr =
+    s"""
+       |${postmanRef.map(r => s"[Test Client (Postman)]($postmanRef)").mkString}
+       |
+       |${specPage.map(sp => s"**[Specification (Confluence)]($sp)**").mkString}
+       |""".stripMargin
+  end companyDescr
+
+end CompanyBpmnDsl
+```
+
+@:callout(info)
+Documentation of `companyDescr` will be in every BPMN element you define by the DSL, e.g. processes or workers.
+@:@

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

@@ -1 +1,52 @@
-# 03-api
+# 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`:
+
+```bash
+03-api/src
+         | main/resources
+         | main/scala/company/api
+         |                     | CompanyApiCreator.scala          
+         | test/scala/company/api       
+```
+
+## CompanyApiCreator
+
+The Company's base class to generate the API documentation and API Clients for Postman.
+
+Example:
+
+```scala mdoc
+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!
+    
+object CompanyApiCreator:
+    lazy val apiConfig = ApiConfig(companyId = "mycompany")
+end CompanyApiCreator
+```
+
+## ApiConfig
+You can define the project structure.
+
+Here an example:
+
+```scala mdoc
+import camundala.api.*
+
+lazy val apiConfig = 
+  ApiConfig(companyId = "mycompany")
+  
+
+```
+
+
+@:callout(info)
+Documentation of `companyDescr` will be in every API documentation. So ones per project.
+@:@

03-api/src/main/scala/camundala/api/ApiConfig.scala

@@ -14,10 +14,6 @@ case class ApiConfig(
     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,
-    openApiPath: os.Path = os.pwd / "openApi.yml",
-    postmanOpenApiPath: os.Path = os.pwd / "postmanOpenApi.yml",
-    openApiDocuPath: os.Path = os.pwd / "OpenApi.html",
-    postmanOpenApiDocuPath: os.Path = os.pwd / "PostmanOpenApi.html",
     // 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
@@ -37,10 +33,15 @@ case class ApiConfig(
     // function to extract project and the reference id from a reference (CallActivity, Dmn or ExternalWorker)
     // default returns the first part of the reference as project (e.g. mycompany from mycompany-product)
     projectRefId: String => (String, String) =
-      pr => pr.split("-").head -> pr
+      pr => pr.split("-").head -> pr,
 ):
   val catalogPath: os.Path = basePath / catalogFileName
 
+  lazy val openApiPath: os.Path = basePath / "03-api" / "OpenApi.yml"
+  lazy val postmanOpenApiPath: os.Path = basePath / "03-api" / "PostmanOpenApi.yml"
+  lazy val openApiDocuPath: os.Path = basePath / "03-api" / "OpenApi.html"
+  lazy val postmanOpenApiDocuPath: os.Path = basePath / "03-api" / "PostmanOpenApi.html"
+
   lazy val projectGroups: Seq[ProjectGroup] = projectsConfig.projectConfigs
     .map(_.group)
     .distinct
@@ -51,10 +52,6 @@ case class ApiConfig(
   def withBasePath(path: os.Path): ApiConfig =
     copy(
       basePath = path,
-      openApiPath = path / "openApi.yml",
-      openApiDocuPath = path / "OpenApi.html",
-      postmanOpenApiPath = path / "postmanOpenApi.yml",
-      postmanOpenApiDocuPath = path / "PostmanOpenApi.html"
     )
 
   def withEndpoint(ep: String): ApiConfig =

04-helper/src/main/scala/camundala/helper/dev/company/CompanyWrapperGenerator.scala

@@ -24,14 +24,13 @@ case class CompanyWrapperGenerator()(using config: DevConfig):
 
   private lazy val bpmnWrapper =
     s"""package $companyName.camundala.bpmn
-       |
-       |import camundala.bpmn.*
-       |import camundala.domain.*
        |
        |/**
        | * Add here company specific stuff, like documentation or custom elements.
        | */
-       |trait CompanyBpmnDsl
+       |trait CompanyBpmnDsl:
+       |  // override def companyDescr = ??? //TODO Add your specific Company Description!
+       |end CompanyBpmnDsl
        |
        |trait CompanyBpmnProcessDsl extends BpmnProcessDsl, CompanyBpmnDsl
        |trait CompanyBpmnServiceTaskDsl extends BpmnServiceTaskDsl, CompanyBpmnDsl
@@ -45,8 +44,6 @@ case class CompanyWrapperGenerator()(using config: DevConfig):
 
   private lazy val apiWrapper =
     s"""package $companyName.camundala.api
-       |
-       |import camundala.api.*
        |
        |/**
        | * Add here company specific stuff, to create the Api documentation and the Postman collection.

04-helper/src/main/scala/camundala/helper/dev/publish/PublishHelper.scala

@@ -16,7 +16,7 @@ case class PublishHelper()(using
   def publish(version: String): Unit =
     println(s"Publishing BPF Package: $version")
     verifyVersion(version)
-    verifySnapshots()
+    //TODO verifySnapshots()
     verifyChangelog(version)
     pushDevelop()
     setApiVersion(version)
@@ -71,7 +71,7 @@ case class PublishHelper()(using
   private def publishToWebserver(): Unit =
     // push it to Documentation Webserver
     publishConfig.foreach:
-      ProjectWebDAV(devConfig.projectName, _).upload()
+      ProjectWebDAV(devConfig.projectName, apiConfig, _).upload()
 
 end PublishHelper
 

04-helper/src/main/scala/camundala/helper/dev/publish/WebDAV.scala

@@ -35,7 +35,7 @@ abstract class WebDAV:
   end startSession
 end WebDAV
 
-case class ProjectWebDAV(projectName: String, publishConfig: PublishConfig) extends WebDAV:
+case class ProjectWebDAV(projectName: String, apiConfig: ApiConfig, publishConfig: PublishConfig) extends WebDAV:
 
   val projectUrl = s"$publishBaseUrl/$projectName/"
 
@@ -58,8 +58,8 @@ case class ProjectWebDAV(projectName: String, publishConfig: PublishConfig) exte
       end try
       // create new
       sardine.createDirectory(projectUrl)
-      sardine.put(s"$projectUrl/OpenApi.html", openApiHtml, contentTypeHtml)
-      sardine.put(s"$projectUrl/openApi.yml", openApiYml, contentTypeYaml)
+      sardine.put(s"${apiConfig.openApiDocuPath}", openApiHtml, contentTypeHtml)
+      sardine.put(s"${apiConfig.openApiPath}", openApiYml, contentTypeYaml)
       postmanApiYml.foreach(pApi =>
         sardine.put(
           s"$projectUrl/postmanCollection.json",

04-helper/src/main/scala/camundala/helper/dev/update/ApiGenerator.scala

@@ -9,8 +9,8 @@ case class ApiGenerator()(using config: DevConfig):
       ) / "ApiProjectCreator.scala",
       api
     )
-    createOrUpdate(config.projectDir / "OpenApi.html", openApiHtml)
-    createOrUpdate(config.projectDir / "PostmanOpenApi.html", postmanOpenApiHtml)
+    createOrUpdate(config.projectDir / "03-api" / "OpenApi.html", openApiHtml)
+    createOrUpdate(config.projectDir / "03-api" / "PostmanOpenApi.html", postmanOpenApiHtml)
   end generate
 
   lazy val api =

04-helper/src/main/scala/camundala/helper/util/VersionHelper.scala

@@ -10,7 +10,7 @@ case class CompanyVersionHelper(
 ):
 
   lazy val companyCamundalaVersion: String =
-    VersionHelper.repoSearch(s"$companyName-camundala-api_3", companyName)
+    VersionHelper.repoSearch(s"$companyName-camundala-bpmn_3", companyName)
 
 end CompanyVersionHelper
 
@@ -65,7 +65,7 @@ end VersionHelper
 object VersionHelper:
 
   lazy val camundalaVersion: String =
-    repoSearch("camundala-api_3", "io.github.pme123")
+    repoSearch("camundala-bpmn_3", "io.github.pme123")
 
   def repoSearch(project: String, org: String): String =
     val searchResult = os.proc(

04-helper/src/test/scala/camundala/helper/util/VersionHelperTest.scala

@@ -7,13 +7,7 @@ class VersionHelperTest extends FunSuite:
   test("repoSearch".ignore) {
     assertEquals(
       VersionHelper.repoSearch("camundala-api_3", "io.github.pme123"),
-      "1.30.24" // This is the latest released version
-    )
-  }
-  test("repoSearch company") {
-    assertEquals(
-      VersionHelper.repoSearch("valiant-camundala-bpmn_3", "valiant"),
-      "0.18.59" // This is the latest released version
+      "1.30.25" // This is the latest released version
     )
   }
   test("repoSearch no result") {

build.sbt

@@ -44,10 +44,13 @@ lazy val root = project
 lazy val docs =
   (project in file("./00-docs"))
     .configure(preventPublication)
-    .settings(projectSettings("docs"))
-    .settings(laikaSettings)
-    .settings(mdocSettings)
+    .settings(
+      projectSettings("docs"),
+      autoImportSetting,
+      laikaSettings,
+      mdocSettings)
     .enablePlugins(LaikaPlugin, MdocPlugin)
+    .dependsOn(helper)
 
 // layer 01
 lazy val domain = project