Baklava
Scala to create different type of documentation (like openapi or ts interfaces) based on routers. Currently it supports akka http and tests written in scalatest or specs2.
A library maintained by Iterators.
Table of contents
Installation
Changes need to be done in build.sbt
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
val baklavaV = "0.0.1-SNAPSHOT"
libraryDependencies += "pl.iterators" %% "baklava-core" % baklavaV % "test"
libraryDependencies += "pl.iterators" %% "baklava-akkahttpscalatest" % baklavaV % "test" # [optional - if you use scalatest]
libraryDependencies += "pl.iterators" %% "baklava-akkahttpspecs2" % baklavaV % "test" # [optional - if you use specs2]
libraryDependencies += "pl.iterators" %% "baklava-formatteropenapi" % baklavaV % "test" # [optional - if you want to generate openapi]
libraryDependencies += "pl.iterators" %% "baklava-formatterts" % baklavaV % "test" # [optional - if you want to generate ts interfaces]
val generateOutputFromRouteDocSpec = inputKey[Unit]("Generate output from route spec")
fullRunInputTask(generateOutputFromRouteDocSpec, Test, "pl.iterators.baklava.core.GenerateOutputFromRouteDocSpec")
fork in generateOutputFromRouteDocSpec := false
Usage
Consider you have spec named: RouteSpec. In order to use, you need to include proper library in dependency and mix in proper trait to your spec (or create a new one trait, which is preferable if you do not want to extends all tests one time).
trait RouteDocSpec extends LibraryAkkaHttpSpecs2RouteDocSpec with KebsArbitraryPredefs with KebsJsonSchemaPredefs with RouteSpec {
override def shutdownSpec() = TestKit.shutdownActorSystem(system, verifySystemShutdown = true)
}
class GetHealthcheckRouteSpec extends RouteDocSpec {
override val routeRepresentation = RouteRepresentation[Unit, TimeResult](
"Returns db status",
"GET",
"/healthcheck"
)
...
}
#todo more examples
#todo document RouteRepresentation interface
#todo split document into generation and serve parts
#todo describe BaklavaRoutes
Generation
In sbt shell:
generateOutputFromRouteDocSpec [packageName] [outputDir] [fetcher] [formatter]
where:
packageName - the package root of your application
outputDir - the directory where you want to generate doc into
fetcher - the fetcher class you want to use for fetch. each of them are provided by separate subprojects.
available options:
- AkkaHttpScalatestFetcher - provided by baklava-akkahttpscalatest
- AkkaHttpSpecs2Fetcher - provided by baklava-akkahttpspecs2
formatter - the formatter class you want to use for generation. each of them are provided by separate subprojects.
available options:
- SimpleOutputFormatter - provided by baklava-core
- OpenApiFormatter - provided by baklava-formatteropenapi
- TsFormatter - provided by baklava-formatterts
- TsStrictFormatter - provided by baklava-formatterts
