ApiBuilder SBT Plugin
A plugin that liberates you from ever needing to use the CLI for updating ApiBuilder definitions.
This plugin requires sbt 1.0.0+
Add the following line to your
addSbtPlugin("io.laserdisc" % "sbt-api-builder" % latestVersion)
That's it! This plugin is automatically installed into every module your project is made of. To disable it for some module(s) you need to add the following line to your project module(s)' definition:
lazy val example = project.in(file(".")) .disablePlugins(ApiBuilderPlugin)
From within an SBT shell you can now access the task:
This task will use the
default profile's token in
to fetch from
https://api.apibuilder.io/ all the resources defined in
src/test/apibuilder/config. All files
are copied in
target/SCALA_BIN_VERSION/src_managed/test, respectively, maintaining
the directory structure and file naming suggested by ApiBuilder.
The above task is also added to the
sourceGenerators setting. This allows
sbt to know that it needs to compile the
src_managed directory also, which
in turn implies that any task that triggers
compile will also trigger
The expected format of the global config file is:
[default] token = some token value [profile name] token = some other token value
that is, the profile name is either
default or it comes after the keyword
The location where to expect this file defaults to
~/.apibuilder but it
can be changed via:
> set Global/apiBuilderGlobalConfigDirectory := file("/foo/bar/somedir")
Likewise, the name of the file defaults to
config but it can be changed via:
> set Global/apiBuilderGlobalConfigFilename := "my_config"
Within this file the
default profile is the one that will be used, unless
instructed otherwise via:
> set Global/apiBuilderProfile := Some("other")
or with the
APIBUILDER_PROFILE environment variable.
Otherwise, the token can be specified with the
APIBUILDER_TOKEN environment variable.
Finally, the ApiBuilder files are expected to be found hitting the endpoint
https://api.apibuilder.io. If that is not the case (e.g. you host an internal
repository), just set the plugin to fetch from a different endpoint:
> set Global/apiBuilderUrl := url("https://acme.org")
The expected format of the local config file follows the convention of one of the flavours of the YAML files that can be defined for the ApiBuilder CLI, specifically:
code: org: project: version: <version> generators: - generator: <generator name>: files: - <file name or file pattern> - generator: <generator name>: files: - <file name or file pattern>
files key is interpreted as a GLOB pattern that files for the
generator) tuple must match for them to be
For example, to build API Builder's api, the following config file is required.
code: apicollective: apibuilder-api: version: latest generators: - generator: http4s_0_18 files: - '*ModelsJson.scala' - '*Server.scala'
As with the global configuration, the directory and the filename of where this
local configuration YAML file is to be found can be changed too.
Since these settings are scoped at Compile and Test configurations
(see sbt documentation),
in order to override the predefined values to
project_root_dir/.apibuilder/test_config (for tests), all it's needed is
> set Compile/apiBuilderCLIConfigDirectory := baseDirectory.value / ".apibuilder" > set Test/apiBuilderCLIConfigDirectory := baseDirectory.value / ".apibuilder"
> set Compile/apiBuilderCLIConfigFilename := "config" // really unchanged, no need to override > set Test/apiBuilderCLIConfigFilename := "test_config"
sbt-api-builder is licensed under the MIT License (the "License"); you may not use this software except in compliance with the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.