Skip to content

Commit

Permalink
Fixing missing OpenApi.yml / adding generic documentation in ApiCreator.
Browse files Browse the repository at this point in the history
  • Loading branch information
pme123 committed Dec 19, 2024
1 parent 866cfad commit aba43a7
Showing 24 changed files with 99 additions and 37 deletions.
4 changes: 2 additions & 2 deletions 00-docs/src/docs/development/initCompany.md
Original file line number Diff line number Diff line change
@@ -48,11 +48,11 @@ open helperCompany.scala
//> using toolkit 0.5.0
//> using dep io.github.pme123::camundala-helper:@VERSION@

import camundala.helper.dev.DevCompanyRunner
import camundala.helper.dev.DevCompanyHelper

@main
def run(command: String, arguments: String*): Unit =
DevCompanyRunner.run(command, arguments*)
DevCompanyHelper.run(command, arguments*)
```

1. Make the file executable:
2 changes: 1 addition & 1 deletion 00-docs/src/docs/exampleApi/OpenApi.html
Original file line number Diff line number Diff line change
@@ -87,7 +87,7 @@
});
}
</script>
<redoc class="content" spec-url='./openApi.yml'></redoc>
<redoc class="content" spec-url='./OpenApi.yml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
4 changes: 2 additions & 2 deletions 00-docs/src/docs/functionalityDsls/apiDoc.md
Original file line number Diff line number Diff line change
@@ -78,7 +78,7 @@ We can group our `api`s.
- This creates a YAML file (Open API) with your documentation.
- In the console you find the paths to the created documentation.

- By default it's here: `YOUR_PROJECT_PATH/openApi.yml`
- By default it's here: `YOUR_PROJECT_PATH/OpenApi.yml`
- There is also a link to an HTML (`YOUR_PROJECT_PATH/OpenApi.html`).
You can copy it from here [OpenApi.html](https://github.com/pme123/camundala-example/blob/master/OpenApi.html)
- Open `OpenApi.html` in a webserver (e.g. from your IDE).
@@ -122,7 +122,7 @@ 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",
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",
21 changes: 13 additions & 8 deletions 03-api/src/main/scala/camundala/api/ApiConfig.scala
Original file line number Diff line number Diff line change
@@ -37,10 +37,10 @@ case class ApiConfig(
):
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 openApiPath: os.Path = basePath / ApiConfig.openApiPath
lazy val postmanOpenApiPath: os.Path = basePath / ApiConfig.postmanOpenApiPath
lazy val openApiDocuPath: os.Path = basePath / ApiConfig.openApiHtmlPath
lazy val postmanOpenApiDocuPath: os.Path = basePath / ApiConfig.postmanOpenApiHtmlPath

lazy val projectGroups: Seq[ProjectGroup] = projectsConfig.projectConfigs
.map(_.group)
@@ -51,7 +51,7 @@ case class ApiConfig(

def withBasePath(path: os.Path): ApiConfig =
copy(
basePath = path,
basePath = path
)

def withEndpoint(ep: String): ApiConfig =
@@ -97,6 +97,11 @@ case class ApiConfig(

lazy val projectConfPath: Path = basePath / projectsConfig.projectConfPath
end ApiConfig
object ApiConfig:
lazy val openApiPath: os.RelPath = os.rel / "03-api" / "OpenApi.yml"
lazy val postmanOpenApiPath: os.RelPath = os.rel / "03-api" / "PostmanOpenApi.yml"
lazy val openApiHtmlPath: os.RelPath = os.rel / "03-api" / "OpenApi.html"
lazy val postmanOpenApiHtmlPath: os.RelPath = os.rel / "03-api" / "PostmanOpenApi.html"

case class ProjectsConfig(
// Path, where the Git Projects are cloned - for dependency check.
@@ -157,10 +162,10 @@ case class ProjectsConfig(

projectNames.find(refIdent.startsWith)
.map(pn =>
refIdent.replace(s"$pn-", "") // case myCompany-myProject-myProcess
refIdent.replace(s"$pn-", "") // case myCompany-myProject-myProcess
.replace(s"$companyId-", "") // case myCompany-myProject > where no myProcess
)
.orElse( // case myProject-myProcess
.orElse( // case myProject-myProcess
projectNames.map(_.replace(s"$companyId-", ""))
.find(refIdent.startsWith)
.map(pn =>
@@ -223,7 +228,7 @@ case class ProjectConfig(
group: ProjectGroup,
color: String = "#fff"
):
def absGitPath(gitDir: os.Path): os.Path = gitDir / name
def absGitPath(gitDir: os.Path): os.Path = gitDir / name
def absBpmnPath(gitDir: os.Path): os.Path = absGitPath(gitDir) / bpmnPath
end ProjectConfig

58 changes: 56 additions & 2 deletions 03-api/src/main/scala/camundala/api/ApiCreator.scala
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
package camundala.api

import camundala.BuildInfo
import camundala.bpmn.InputParams
import camundala.domain.*
import com.typesafe.config.ConfigFactory
import io.circe.Encoder
import sttp.apispec.openapi.*
import sttp.apispec.openapi.circe.yaml.*
@@ -12,10 +14,11 @@ import sttp.tapir.docs.openapi.{OpenAPIDocsInterpreter, OpenAPIDocsOptions}
import java.text.SimpleDateFormat
import java.util.Date
import scala.util.matching.Regex
import scala.jdk.CollectionConverters.*

trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:

protected def companyDescr: String
protected def companyProjectVersion: String
protected def projectDescr: String

def supportedVariables: Seq[InputParams] =
@@ -254,6 +257,47 @@ trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:
matches.foldLeft(line)((a, b) => a.replace(b, s"[$b]($url/$b)"))
replaceJira(changed, tail.toMap)

protected def packageConf =
if packageConfPath.toIO.exists() then
s"""# Package Configuration
|**Check all dependency trees here: [$projectName](../../dependencies/$projectName.html)**
|
|$dependencies
|
|<details>
|<summary>${apiConfig.projectsConfig.projectConfPath}</summary>
|<p>
|
|```
|
|${os.read(packageConfPath).trim}
|
|```
|
|</p>
|</details>
|""".stripMargin
else ""

protected def dependencies: String =

def docPortal(pckg: String) = apiConfig.docProjectUrl(pckg) / "OpenApi.html"

val projects = apiConfig.projectsConfig.groupedConfigs.flatMap(_.projects)
println(s"Projects: $projects")
def documentations =
projects.map(pc => pc.name -> docPortal(pc.name)).toMap

s"""|### Dependencies:
|
|${
apiProjectConf.dependencies
.map(dep => s"- _**[${dep.name}](${documentations.getOrElse(dep.name, "NOT FOUND")})**_")
.mkString("\n")
}
|""".stripMargin
end dependencies

protected def createReadme(): String =
val readme = basePath / "README.md"
if readme.toIO.exists() then
@@ -264,20 +308,26 @@ trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:

protected def description: String =
s"""
|$companyDescr
|
|$projectDescr
|
|Created at ${SimpleDateFormat().format(new Date())}
|
|**See the [Camundala Documentation](https://pme123.github.io/camundala/)**
|
|$packageConf
|
|${createReadme()}
|
|${createChangeLog()}
|
|${createGeneralVariables()}
|
|> Created with:
|> - [camundala-api v${BuildInfo.version}](https://github.com/pme123/camundala)
|> - ${apiProjectConf.org}-camundala-api $companyProjectVersion
|> - ${apiProjectConf.org}-camundala-helper
|
|""".stripMargin

protected def postmanDescription: String =
@@ -347,4 +397,8 @@ trait ApiCreator extends PostmanApiCreator, TapirApiCreator, App:
private def listOfStringsOrCommaSeparated(example: String) =
s"""It is also possible to use a _comma separated_ String,
|like `"$example"`""".stripMargin

private lazy val packageConfPath = apiConfig.basePath / apiConfig.projectsConfig.projectConfPath
private lazy val apiProjectConf = ApiProjectConf(packageConfPath)

end ApiCreator
2 changes: 1 addition & 1 deletion 03-api/src/test/scala/camundala/api/ApiCreatorTest.scala
Original file line number Diff line number Diff line change
@@ -16,7 +16,7 @@ class ApiCreatorTest extends munit.FunSuite, DefaultApiCreator:
def title: String = ???
def version: String = ???

lazy val companyDescr: String = ""
lazy val companyProjectVersion: String = "0.1.0"
lazy val projectDescr: String = ""

test("testReplaceJira") {
2 changes: 1 addition & 1 deletion 03-api/src/test/scala/camundala/api/TestApiCreator.scala
Original file line number Diff line number Diff line change
@@ -12,7 +12,7 @@ object TestApiCreator extends DefaultApiCreator, BpmnProcessDsl, App:
def title = "Test API"

def version = "1.0"

lazy val companyProjectVersion: String = "0.1.0"
lazy val projectDescr: String = ""

override val apiConfig: ApiConfig =
2 changes: 1 addition & 1 deletion 04-helper/src/main/resources/OpenApi.html
Original file line number Diff line number Diff line change
@@ -74,7 +74,7 @@
});
}
</script>
<redoc spec-url='./openApi.yml'></redoc>
<redoc spec-url='./OpenApi.yml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>

</body>
Original file line number Diff line number Diff line change
@@ -11,11 +11,11 @@ case class CompanyScriptCreator()(using config: DevConfig):
|//> using toolkit 0.5.0
|//> using dep io.github.pme123::camundala-helper:${VersionHelper.camundalaVersion}
|
|import camundala.helper.dev.DevCompanyRunner
|import camundala.helper.dev.DevCompanyHelper
|
| @main
| def run(command: String, arguments: String*): Unit =
| DevCompanyRunner.run(command, arguments*)
| DevCompanyHelper.run(command, arguments*)
|""".stripMargin

lazy val companyCamundalaHelper =
Original file line number Diff line number Diff line change
@@ -43,7 +43,8 @@ case class CompanyWrapperGenerator()(using config: DevConfig):
|""".stripMargin

private lazy val apiWrapper =
s"""package $companyName.camundala.api
s"""package $companyName.camundala
|package api
|
|/**
| * Add here company specific stuff, to create the Api documentation and the Postman collection.
@@ -53,7 +54,7 @@ case class CompanyWrapperGenerator()(using config: DevConfig):
| // 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 = "$companyName")
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
package camundala.helper.dev.publish

import camundala.api.ApiConfig
import camundala.helper.dev.publish.ChangeLogUpdater
import camundala.helper.util.{DevConfig, Helpers, PublishConfig}
import com.typesafe.config.{Config, ConfigFactory}

case class PublishHelper()(using
devConfig: DevConfig,
Original file line number Diff line number Diff line change
@@ -58,8 +58,8 @@ case class ProjectWebDAV(projectName: String, apiConfig: ApiConfig, publishConfi
end try
// create new
sardine.createDirectory(projectUrl)
sardine.put(s"${apiConfig.openApiDocuPath}", openApiHtml, contentTypeHtml)
sardine.put(s"${apiConfig.openApiPath}", openApiYml, contentTypeYaml)
sardine.put(s"$projectUrl/OpenApi.html", openApiHtml, contentTypeHtml)
sardine.put(s"$projectUrl/OpenApi.yml", openApiYml, contentTypeYaml)
postmanApiYml.foreach(pApi =>
sardine.put(
s"$projectUrl/postmanCollection.json",
@@ -104,7 +104,7 @@ case class ProjectWebDAV(projectName: String, apiConfig: ApiConfig, publishConfi
private lazy val openApiHtml =
os.read.inputStream(publishConfig.openApiHtmlPath)
private lazy val openApiYml = os
.read(os.pwd / "openApi.yml")
.read(apiConfig.openApiPath)
.getBytes(StandardCharsets.UTF_8)
private lazy val postmanApiYml =
val path = os.pwd / "postmanCollection.json"
Original file line number Diff line number Diff line change
@@ -200,7 +200,7 @@ case class ApiGenerator()(using config: DevConfig):
| });
| }
|</script>
|<redoc class="content" spec-url='./openApi.yml'></redoc>
|<redoc class="content" spec-url='./OpenApi.yml'></redoc>
|<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
|</body>
|</html>
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package camundala.helper.openApi

import camundala.api.ApiConfig
import camundala.helper.util.ModuleConfig

case class OpenApiConfig(
Original file line number Diff line number Diff line change
@@ -14,6 +14,7 @@ object ProjectApiCreator extends DefaultApiCreator:
protected val title = "Demos Example Process API"

protected val version = "1.0"
lazy val companyProjectVersion: String = "0.1.0"

lazy val companyDescr: ExampleName = ""
lazy val projectDescr: ExampleName = ""
2 changes: 1 addition & 1 deletion 05-examples/demos/OpenApi.html
Original file line number Diff line number Diff line change
@@ -87,7 +87,7 @@
});
}
</script>
<redoc class="content" spec-url='./openApi.yml'></redoc>
<redoc class="content" spec-url='./OpenApi.yml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
Original file line number Diff line number Diff line change
@@ -19,6 +19,7 @@ object ProjectApiCreator extends DefaultApiCreator:
protected val title = "Invoice Example Process API"
// version of your project
protected val version = "1.0"
lazy val companyProjectVersion: String = "0.1.0"

lazy val companyDescr: String = ""
lazy val projectDescr: String = ""
2 changes: 1 addition & 1 deletion 05-examples/invoice/OpenApi.html
Original file line number Diff line number Diff line change
@@ -87,7 +87,7 @@
});
}
</script>
<redoc class="content" spec-url='./openApi.yml'></redoc>
<redoc class="content" spec-url='./OpenApi.yml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
Original file line number Diff line number Diff line change
@@ -15,7 +15,7 @@ object ProjectApiCreator extends DefaultApiCreator:

val version = "1.0"

lazy val companyDescr: String = ""
lazy val companyProjectVersion: String = "0.1.0"
lazy val projectDescr: String = ""

document(
Original file line number Diff line number Diff line change
@@ -17,6 +17,7 @@ object TwitterApiCreator extends DefaultApiCreator:
def title = "Twitter Process API C8"

def version = "1.0"
lazy val companyProjectVersion: String = "0.1.0"

document {
api(twitterDemoProcess)(
2 changes: 1 addition & 1 deletion 05-examples/twitter/OpenApi.html
Original file line number Diff line number Diff line change
@@ -87,7 +87,7 @@
});
}
</script>
<redoc class="content" spec-url='./openApi.yml'></redoc>
<redoc class="content" spec-url='./OpenApi.yml'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
4 changes: 2 additions & 2 deletions docs/development/initCompany.html
Original file line number Diff line number Diff line change
@@ -139,11 +139,11 @@ <h1 id="init-company" class="title">Init Company</h1>
</span><span class="comment">//&gt; using toolkit 0.5.0
//&gt; using dep io.github.pme123::camundala-helper:1.30.25
</span><span>
</span><span class="keyword">import</span><span> </span><span class="identifier">camundala</span><span>.</span><span class="identifier">helper</span><span>.</span><span class="identifier">dev</span><span>.</span><span class="type-name">DevCompanyRunner</span><span>
</span><span class="keyword">import</span><span> </span><span class="identifier">camundala</span><span>.</span><span class="identifier">helper</span><span>.</span><span class="identifier">dev</span><span>.</span><span class="type-name">DevCompanyHelper</span><span>

</span><span class="annotation">@main</span><span>
</span><span class="keyword">def</span><span> </span><span class="declaration-name">run</span><span>(</span><span class="identifier">command</span><span>: </span><span class="type-name">String</span><span>, </span><span class="identifier">arguments</span><span>: </span><span class="type-name">String</span><span>*): </span><span class="type-name">Unit</span><span> =
</span><span class="type-name">DevCompanyRunner</span><span>.</span><span class="identifier">run</span><span>(</span><span class="identifier">command</span><span>, </span><span class="identifier">arguments</span><span>*)</span></code></pre>
</span><span class="type-name">DevCompanyHelper</span><span>.</span><span class="identifier">run</span><span>(</span><span class="identifier">command</span><span>, </span><span class="identifier">arguments</span><span>*)</span></code></pre>
</li>
<li>
<p>Make the file executable:</p>
Loading
Oops, something went wrong.

0 comments on commit aba43a7

Please sign in to comment.