Mill plugin for guardrail generation
import $ivy.`io.github.jackcviers::mill-guardrail::<release-version>`
import io.github.jackcviers.mill.guardrail._
object MyModule extends Guardrail{
override def ivyDeps = T.task{
super.ivyDeps() ++ Agg(
// specific dedendencies for the framework and guardrail extensions you choose to use.
)
}
}
By default, this will generate scala code for the server, client, and
model dto files in the guardrail spec files using the defualt
guardrail args for scala and use the http4s framework without tracing,
custom extraction, or auth and with empty modules ignoring tags. You
can override this task and set your own framework and
dev.Guardrail.Args
for each spec file, including the contextual
arguments for dev.guardrail.Context
, which controls tracing, custom
extraction, module loading, tag behaviors, and auth implementations
during module compilation. See the Guardrail
documentation for all the possible
configuration options, and tests in the itest
module for some
demonstrations.
Guardrail only outputs scala 2.13 sources at the moment. You may consider separating your generated sources in their own modules and depending upon them for Scala 3 modules, as Scala 3 can use 2.13 dependencies.
mill-guardrail is compatible with mill 0.11.x+.
By default, mill-guardrail will look in <modulePath>/guardrail/
for
specification json/yml/yaml files. You may customize this by
overriding Guardrail#guardrailDirectories
in your module definition.
By default, mill-guardrail will identify all json, yaml, and yml files in the Guardrail#guardrailDirectories and their children. You can override this behavior by overriding Guardrail#guardrailSpecFiles in your module definition. Commonly, you may want to filter out a specific spec file. See the example below:
object MyModule extends Guardrail{
override def guardrailSpecFiles = T.sources {
super
.guardrailSpecFiles()
.filter{ pathRef =>
!pathRef.path.lastOption.exists(_.contains("specFileToFilter"))
}
}
}
You can choose the framework, language for code generation, and the
other guardrail-specific settings by overriding
Guardrail#guardrailTasks
in your module. Typically, you may want to
filter out the client, server, or model generation for the
specifications. The tasks are returned in an
Agg[Guardrail.LanguageAndArgs]
. An example removing server
generation from the default arguments is below:
import dev.{guardrail => dg}
// ...
object MyModule extends Guardrail{
override def guardrailTasks: define.Task[Agg[Guardrail.LanguageAndArgs]] = T.task{
super.guardrailTasks().map{ (languageAndArgs: Guardrail.LanguageAndArgs) =>
languageAndArgs.copy(args = languageAndArgs.args.filterNot{ a: (dg.Args) =>
a.kind == CodegenTarget.Server
})
}
}
}
See the itest
test modules build.sc
and the Guardrail
documentation for more information on how to
customize the language, framework, and Guardrail extension and module
definitions.
- Scala Default (Http4s Client/Server/Models/Circe)
- Scala Default No Server (Http4s/Circe)
- Scala akka-http
- Scala akka-http-jackson
Java code generation does not work, pending an answer to guardrail/issues/1953.
All code contributed to this repository MUST include the generated
license header, generated using
https://index.scala-lang.org/lewisjkl/header
. The build for PRs will
run ./mill __.headerCheck
and fail if these headers are not created.
You can add the headers to any files you add with ./mill __.headerCreate
before comitting.
millguardrail
contains the plug-in source files. The project is set
up for mill cross-building. Inside millguardrail
, src-0.11
contains the mill 0.11.x
-specific files. Contributions extending the
plug-in to earlier versions of mill are greatly appreciated.
itest
contains the plug-in tests themselves. Issue pull-requests are
welcome with only a test in itest
to assist with replication.
This plug-in was heavily influenced by sbt-guardrail, though it is not quite a 1:1 port.
The build structure was heavily influenced by mill-vcs-version.