How upstart-commerce/sbt-openapi-generator works
Project type and purpose
• This is an SBT plugin (“sbt-openapi-generator”) written in Scala.
• Purpose: to integrate OpenAPI Generator into an SBT build, allowing users to point at an OpenAPI spec and invoke an openapiGenerate task that emits client/server code according to configured templates.
File structure
• Top‐level files:
• build.sbt, version.sbt – the plugin’s build definition
• project/ – the SBT meta-build (plugins.sbt, build.properties)
• LICENSE, .gitignore, .travis.yml, .scalafmt.conf – CI and formatting configs
• Source layout under src/main/scala/org/upstartcommerce/openapi:
• OpenAPIGeneratorPlugin.scala – the plugin entry point (registers tasks, settings)
• OpenAPIGeneratorKeys.scala – defines all setting/task keys
• Test harness under src/sbt-test:
• Two sample test projects (“remote” and “simple”) with their own build.sbt, spec files, and plugin settings – used by SBT’s scripted test runner.
README for additional insights
• Usage instructions: how to include the plugin in project/plugins.sbt, enable it in build.sbt, and configure two mandatory settings (openapiInputSpec, openapiGeneratorName).
• Dozens of optional settings for fine-tuning generator behavior, templating, output paths, import mappings, etc.
a. Main components
• SBT Build Environment
• OpenAPIGeneratorPlugin (entry point)
• OpenAPIGeneratorKeys (settings & tasks registry)
• Task Graph / Trigger (openapiGenerate task)
• OpenAPI Generator CLI/Engine (third‐party library invoked by the plugin)
• File I/O (reading spec, writing generated sources)
• Template Engine (Mustache or Handlebars)
• Optional Post-Processing Module (driven by openapiEnablePostProcessFile)
• Test Harness (scripted tests under sbt-test)
b. Relationships & interactions
1. User’s build.sbt → enables plugin and sets keys
2. SBT loads OpenAPIGeneratorPlugin → registers keys & tasks
3. On openapiGenerate:
– Plugin reads settings (spec URI, generatorName, outputDir, additionalProperties, etc.)
– Fetches spec (local file or HTTP if remote authentication is set)
– Invokes OpenAPI Generator engine with chosen templates & settings
– Receives generated code artifacts
– (Optional) Post-process files via environment/script hooks
– Writes output to target directory
4. Scripted Test Harness:
– SBT’s scripted runner spins up sample projects
– Verifies that code generation completes and output matches expected structure
c. Architectural patterns & design principles
• SBT Plugin API pattern: define SettingsKey, TaskKey, AutoPlugin to hook into build lifecycle
• Separation of concerns:
– Keys/Settings definition (OpenAPIGeneratorKeys)
– Plugin wiring (OpenAPIGeneratorPlugin)
– External engine invocation (wrapping OpenAPI Generator CLI)
– File and template management
• Extensibility: almost all aspects of generation are exposed via SBT settings, enabling end users to customize behavior or override templates.
d. Key technologies & libraries
• Scala & sbt AutoPlugin API
• openapi-generator (Java CLI / library)
• Mustache / Handlebars templating
• sbt‐scripted test runner
Final reminders
• Every key setting as an input to the plugin.
• Both local file and remote HTTP spec paths.
• Detail the optional post‐processing step.
• Sbt-test directory as a validation sub-system that verifies end-to-end behavior.