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("com.sirocchj" % "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
~/.apibuilder/config 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 saved.
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 the following:
> 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.