Put every generation setting in one config file under version control: generator name, input spec, output path, config options and any additional properties. Then review changes to it like code. These settings decide what gets written, so an unreviewed change is an unreviewed change to your product.
Three kinds of setting
The configuration page distinguishes types of options:
- Global properties control generation across generators, such as which APIs or models to produce.
- Config options are specific to one generator and validated by it.
- Additional properties are passed to templates. They are often used to give custom templates user defined values.
The CLI accepts config options as additional properties. The page also notes that tool specific top level options, such as those for the Maven or Gradle plugin, may look like duplicates of config options but are declared differently by each tool.
Why it needs review
Small settings have large effects.
| Setting | Effect |
|---|---|
| Choice of generator or library | Changes the HTTP client and the dependencies written into the build file |
| Package and naming options | Affect how callers import the client |
| Selective generation properties | Change which operations exist in the client |
| Skip validation flag | Lets a broken spec generate code |
| Custom template directory | Swaps built in templates for yours |
| Additional properties for templates | Whatever you pass lands in generated text |
The tool also lists options per generator through a config help command, so you can see what is available and the default of each, rather than guessing.
How to manage it
- Use a single config file per generated client and commit it beside the spec.
- Keep the input spec path, the output directory and the generator version in or next to it.
- Require review from a code owner for changes to the file.
- Comment non obvious choices. Each tool format differs, but a note in the pull request is enough if comments are not supported.
- Avoid putting secrets in it. Values passed as additional properties can end up inside generated files, which may be published.
- In CI, run the generator with only this file as its input and compare the output to what is committed.
Plugins and the CLI differ
The page gives an example of how one option is written differently across the CLI, Maven, Gradle and sbt plugins. If your team uses more than one tool to generate, expect the same intent to look different, and keep a table of the equivalents. A mismatch can cause one pipeline to generate something another does not.
Link it to your audit trail
Compliance reviewers like to see that the way code is produced is controlled. A reviewed config file, a pinned version and a CI comparison step are good evidence. For wider ideas on evidence, see system generated reports as audit evidence.
Where Safeguard fits
Safeguard's policies and gates apply to configuration changes in pull requests, and compliance and evidence automation helps you keep records of reviews and checks for audits.
Quick check
Are additional properties safe for secrets?
No. They are passed to templates and can appear in generated output, so keep secrets out.
Can I discover valid options without reading the source?
Yes. The docs describe a config help command that prints the options for a chosen generator.
Sources
Last reviewed: 19 October 2026.
