How do you wire openapi-generator into a build so generated code stays maintainable?

## Generated code is build output, not source The single decision that prevents most pain: generated files live under the build output directory and are on the same footing as compiled classes. They are recreated from an input, they are not reviewed line by line, and they are never edited. When generated code is written into `src` instead, three things follow — somebody eventually fixes a bug by editing it, the next regeneration silently reverts that fix, and from then on nobody trusts the pipeline and regeneration becomes a manual ritual performed nervously. If a specific file truly must survive regeneration, `.openapi-generator-ignore` (same syntax idea as an ignore file) excludes it explicitly, which at least makes the exception visible. ## Pin everything that affects the output The output is a function of three inputs, and all three need pinning. **The generator version.** Templates, naming rules and library defaults change between releases. An unpinned generator means the same spec produces different code on different days and on different machines — the classic "works locally, breaks in CI" for generated projects. Pin it in the build file, and treat a bump as a change to be reviewed like a dependency upgrade, because it is one. **The spec input.** Generate from a file in the repository. Pointing `-i` at a live URL makes your build depend on someone else's uptime, gives you no record of what you built against, and lets a remote edit change your code with no diff anywhere. Vendor third-party specs and update them deliberately. **The options.** Keep `--additional-properties` and any custom templates in the build configuration under version control, never in someone's shell history. If you fork templates, that fork is now code you maintain across generator upgrades — a real cost, so fork only when configuration cannot do the job. ## Commit the output, or regenerate every build? Both are defensible; what matters is choosing on purpose. *Committing* the generated code gives you a visible diff whenever the contract changes, keeps the build simple for anyone without the generator toolchain installed, and makes IDE navigation trivial. The cost is repository noise and the risk of a stale commit if someone changes the spec and forgets to regenerate — mitigated by a CI step that regenerates and fails on any difference. *Generating every build* guarantees freshness and keeps the repository clean, at the price of a toolchain dependency (often a JVM plus the generator), slower cold builds, and contract changes that are invisible in review because no file changed. A reasonable default: generate at build time for internal services where the spec lives in the same repository, and commit the output for published SDKs where consumers want to read the code and the diff is the release note. ## Contain the blast radius Generated clients are not neutral. Their models carry serialisation annotations, their nullability reflects the spec's `required`/`nullable` accuracy, and their method names change when the spec's `operationId`s or tags change. Let those types spread through your codebase and every regeneration becomes a wide refactor. The containment pattern is a thin adapter: one small module that depends on the generated client, exposes your own interface in your own domain types, and maps between them. Regeneration then breaks at most that module. It also means a decision to switch generators, or to hand-write the client, is a local change. The same applies on the server side. Implement the generated interface in a controller that immediately delegates to your service layer, so generated request/response models never reach your domain logic. ## Make the contract change visible Whatever the layout, the change you must not miss is a contract change. Wire generation into the normal build task graph so a compile failure appears the moment the implementation stops satisfying the spec — that compile error is the feature. Add a CI job that regenerates from the committed spec, and if you commit the output, fail on any difference. And validate or lint the spec before generating, because a generator will happily produce plausible garbage from a document that a linter would have rejected in a second.