Added tags description in ApiCreator.

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

@@ -9,7 +9,10 @@ import scala.reflect.ClassTag
 trait ApiBaseDsl:
 
   def group(name: String)(apis: InOutApi[?, ?]*): CApiGroup =
-    CApiGroup(name, apis.toList)
+    group(name, "")(apis*)
+
+  def group(name: String, description: String)(apis: InOutApi[?, ?]*): CApiGroup =
+    CApiGroup(name, description, apis.toList)
 
   def api[
       In <: Product: InOutEncoder: InOutDecoder: Schema,

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

@@ -1,9 +1,12 @@
 package camundala.api
 
 import camundala.bpmn.InputParams
-import camundala.domain.MockedServiceResponse
+import camundala.domain.*
+import io.circe.Encoder
 import sttp.apispec.openapi.*
 import sttp.apispec.openapi.circe.yaml.*
+import sttp.tapir.*
+import sttp.tapir.docs.apispec.DocsExtension
 import sttp.tapir.docs.openapi.{OpenAPIDocsInterpreter, OpenAPIDocsOptions}
 
 import java.text.SimpleDateFormat
@@ -43,15 +46,23 @@ trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:
     println(s"Check Open API Docu: ${apiConfig.openApiDocuPath}")
   end writeOpenApis
 
-  protected lazy val openAPIDocsInterpreter =
+  protected lazy val openAPIDocsInterpreter      =
     OpenAPIDocsInterpreter(docsOptions =
       OpenAPIDocsOptions.default.copy(defaultDecodeFailureOutput = _ => None)
     )
-
+  import sttp.tapir.json.circe.*
   protected def openApi(apiDoc: ApiDoc): OpenAPI =
     val endpoints = create(apiDoc)
     openAPIDocsInterpreter
-      .toOpenAPI(endpoints, info(title, Some(description)))
+      .toOpenAPI(
+        endpoints,
+        info(title, Some(description)),
+        docsExtensions = List(DocsExtension.of(
+          "tags",
+          apiDoc.groupTags.asJson
+        ))
+      )
+
   end openApi
 
   protected def postmanOpenApi(apiDoc: ApiDoc): OpenAPI =
@@ -235,9 +246,9 @@ trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:
       jiraUrls: Map[String, String]
   ): String =
     jiraUrls.toList match
-      case Nil => line
+      case Nil                => line
       case (k -> url) :: tail =>
-        val regex = Regex(s"""$k-(\\d+)""")
+        val regex   = Regex(s"""$k-(\\d+)""")
         val matches = regex.findAllIn(line).toSeq
         val changed =
           matches.foldLeft(line)((a, b) => a.replace(b, s"[$b]($url/$b)"))
@@ -293,7 +304,7 @@ trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:
     val catalogPath = apiConfig.catalogPath
     if os.exists(catalogPath) then
       os.remove(catalogPath)
-    val catalog = toCatalog(apiDoc)
+    val catalog     = toCatalog(apiDoc)
     os.write(catalogPath, catalog)
     println(s"Created Catalog $catalogPath")
   end writeCatalog
@@ -310,9 +321,9 @@ trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:
     apiDoc.apis.foldLeft(List.empty[(InOutApi[?, ?], String)]) {
       case (result, groupedApi: ProcessApi[?, ?, ?]) =>
         result ++ (groupedApi.apis :+ groupedApi).map(_ -> groupedApi.name)
-      case (result, groupedApi: GroupedApi) =>
+      case (result, groupedApi: GroupedApi)          =>
         result ++ groupedApi.apis.map(_ -> groupedApi.name)
-      case (result, _) =>
+      case (result, _)                               =>
         result
     }.distinct
 

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

@@ -10,10 +10,18 @@ import scala.annotation.targetName
 import scala.reflect.ClassTag
 import scala.util.Random
 
-case class ApiDoc(apis: List[CApi])
+case class ApiDoc(apis: List[CApi]):
+  lazy val groupTags: List[ApiTag] = apis.flatMap(_.groupTag)
+end ApiDoc
+
+case class ApiTag(name: String, description: String, `x-displayName`: String)
+object ApiTag:
+  given InOutCodec[ApiTag] = deriveInOutCodec
+//  given ApiSchema[ApiTag] = deriveApiSchema // problem with magnolia
 
 sealed trait CApi:
   def name: String
+  def groupTag: Option[ApiTag] = None
 
 sealed trait GroupedApi extends CApi:
   def name: String
@@ -28,10 +36,10 @@ sealed trait InOutApi[
   def inOut: InOut[In, Out, ?]
   def apiExamples: ApiExamples[In, Out]
   lazy val inOutDescr: InOutDescr[In, Out] = inOut.inOutDescr
-  lazy val id: String = inOutDescr.id
-  lazy val descr: String = inOut.descr.getOrElse("")
-  lazy val typeName: String = inOut.typeName
-  lazy val inOutType: InOutType = inOut.inOutType
+  lazy val id: String                      = inOutDescr.id
+  lazy val descr: String                   = inOut.descr.getOrElse("")
+  lazy val typeName: String                = inOut.typeName
+  lazy val inOutType: InOutType            = inOut.inOutType
 
   def withExamples(
       examples: ApiExamples[In, Out]
@@ -55,11 +63,11 @@ sealed trait InOutApi[
 
   lazy val inJson: Option[Json] = inOut.in match
     case _: NoInput => None
-    case _ => Some(inOut.in.asJson.deepDropNullValues)
+    case _          => Some(inOut.in.asJson.deepDropNullValues)
 
   lazy val outJson: Option[Json] = inOut.out match
     case _: NoInput => None
-    case _ => Some(inOut.out.asJson.deepDropNullValues)
+    case _          => Some(inOut.out.asJson.deepDropNullValues)
 
   lazy val variableNamesIn: List[String] =
     inOut.in.productElementNames.toList
@@ -83,13 +91,13 @@ sealed trait InOutApi[
       diagramDownloadPath: String,
       diagramNameAdjuster: Option[String => String]
   ): String =
-    val postfix = if typeName == "Process" then "bpmn" else "dmn"
-    val postfixUpper = postfix.head.toUpper + postfix.tail
+    val postfix         = if typeName == "Process" then "bpmn" else "dmn"
+    val postfixUpper    = postfix.head.toUpper + postfix.tail
     val pureDiagramName = diagramName.getOrElse(id)
-    val name =
+    val name            =
       diagramNameAdjuster.map(_(pureDiagramName)).getOrElse(pureDiagramName)
-    val fileName = s"$name.$postfix"
-    val randomPostfix = Random.nextInt(100000)
+    val fileName        = s"$name.$postfix"
+    val randomPostfix   = Random.nextInt(100000)
     s"""
        |<div class="diagramCanvas">
        |  <div class="diagram" id="$name-$randomPostfix">
@@ -135,15 +143,15 @@ case class ProcessApi[
        |
        |${inOut.in match
         case _: GenericServiceIn => "" // no diagram if generic
-        case _ =>
+        case _                   =>
           diagramDownloadPath
             .map(diagramFrame(_, diagramNameAdjuster))
             .getOrElse("")
       }
        |${generalVariablesDescr(inOut.out, "")}""".stripMargin
 
       // this function needs to be here as circe does not find the JsonEncoder in the extension method
-  lazy val initInMapper: EndpointIO.Body[String, InitIn] = jsonBody[InitIn]
+  lazy val initInMapper: EndpointIO.Body[String, InitIn]                = jsonBody[InitIn]
 
 end ProcessApi
 
@@ -200,7 +208,7 @@ sealed trait ExternalTaskApi[
   def inOut: ExternalTask[In, Out, ?]
 
   def processName: String = inOut.processName
-  lazy val topicName = inOut.topicName
+  lazy val topicName      = inOut.topicName
 
   override def apiDescription(
       diagramDownloadPath: Option[String],
@@ -257,7 +265,7 @@ case class ServiceWorkerApi[
     inOut.defaultServiceOutMock match
       case seq: Seq[?] =>
         s"Seq[${seq.head.getClass.getName.replace("$", " > ")}]"
-      case other => other.getClass.getName.replace("$", " > ")
+      case other       => other.getClass.getName.replace("$", " > ")
 end ServiceWorkerApi
 
 object ServiceWorkerApi:
@@ -342,10 +350,12 @@ end DecisionDmnApi
 
 case class CApiGroup(
     name: String,
+    description: String,
     apis: List[InOutApi[?, ?]]
 ) extends GroupedApi:
 
   def withApis(apis: List[InOutApi[?, ?]]): CApiGroup = copy(apis = apis)
+  override def groupTag: Option[ApiTag] = Some(ApiTag(name, description, name))
 
 end CApiGroup
 

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

@@ -2,6 +2,7 @@ package camundala.api
 
 import os.CommandResult
 import camundala.bpmn.shortenName
+import camundala.domain.*
 
 val catalogFileName = "catalog.md"
 val defaultProjectPath = os.rel / "PROJECT.conf"

05-examples/invoice/03-api/src/main/scala/camundala/examples/invoice/api/ProjectApiCreator.scala

@@ -34,13 +34,13 @@ object ProjectApiCreator extends DefaultApiCreator:
       ReviewInvoice.AssignReviewerUT.example,
       ReviewInvoiceUT
     ),
-    group("Workers")(
+    group("Workers", "All my super Workers")(
       StarWarsPeopleDetail.example
         .withOutExample("Success", StarWarsPeopleDetail.Out.Success())
         .withOutExample("Failure", StarWarsPeopleDetail.Out.Failure()),
       api(ArchiveInvoice.example)
     ),
-    group("User Tasks")(
+    group("User Tasks", "All the User Interfaces.")(
       api(ApproveInvoiceUT), // api( is optional
       InvoiceReceipt.PrepareBankTransferUT.example,
       ReviewInvoice.AssignReviewerUT.example,

05-examples/invoice/catalog.md

@@ -1,8 +1,8 @@
 ### Invoice Example Process API
-- [Bpmn: example-invoice-c7-review](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Bpmn:%20example-invoice-c7-review)
-- [Bpmn: example-invoice-c7](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Bpmn:%20example-invoice-c7)
-- [Dmn: example-invoice-c7-assignApprover](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Dmn:%20example-invoice-c7-assignApprover)
-- [Dmn: example-invoice-c7-assignApprover](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Dmn:%20example-invoice-c7-assignApprover)
+- [Bpmn: c7-review](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Bpmn:%20c7-review)
+- [Bpmn: c7](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Bpmn:%20c7)
+- [Dmn: c7-assignApprover](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Dmn:%20c7-assignApprover)
+- [Dmn: c7-assignApprover](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Dmn:%20c7-assignApprover)
 - [UserTask: ApproveInvoiceUT](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/UserTask:%20ApproveInvoiceUT)
 - [UserTask: ApproveInvoiceUT](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/UserTask:%20ApproveInvoiceUT)
 - [UserTask: AssignReviewerUT](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/UserTask:%20AssignReviewerUT)
@@ -13,4 +13,4 @@
 - [UserTask: ReviewInvoiceUT](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/UserTask:%20ReviewInvoiceUT)
 - [Worker: ArchiveInvoiceService](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Worker:%20ArchiveInvoiceService)
 - [Worker: ArchiveInvoiceService](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Worker:%20ArchiveInvoiceService)
-- [Worker: star-wars-api-people-detail](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Worker:%20star-wars-api-people-detail)
+- [Worker: api-people-detail](https://webstor.ch/camundala/myCompany/example-invoice/OpenApi.html#operation/Worker:%20api-people-detail)