Generating clients and server stubs from an OpenAPI document, and keeping them generated

Goal

Derive typed client libraries and server-side request and response types from the OpenAPI document, so that the document remains the single contract and hand-written code cannot quietly diverge from it.

Prerequisites

An OpenAPI document that validates, with an operationId on every operation: the specification defines it as a unique string used to identify the operation, which tools may use to identify operations, and generators derive method names from it. A generator whose output language you can read; OpenAPI Generator lists client generators and server generators per language. A decision on where generated code lives: committed to the repository, or produced during the build.

Steps

1. Pin the generator version in the repository (a container image tag or a wrapper script). Generated output changes between generator versions, and an unpinned generator produces spurious diffs.
2. Generate into a dedicated directory that contains nothing hand-written. Put the exact command in the task runner so that everyone, including CI, regenerates the same way.
3. Configure rather than edit: the usage documentation lists --additional-properties for generator options, --type-mappings for type substitutions and --template-dir for copied templates when the output needs structural changes. The customization documentation describes .openapi-generator-ignore, modelled on .gitignore, as the way to keep the generator from overwriting listed files, such as a README or a wrapper you maintain by hand.
4. For servers, generate only interfaces and models, implement them in separate files, and let the compiler report every operation that is missing or whose signature changed.
5. For clients, wrap the generated client in a thin hand-written layer that adds retries, authentication and logging, so the generated part can be replaced wholesale.
6. Add a CI job that regenerates and fails on git diff --exit-code when output is committed; when it is not committed, make the build depend on the generation step.
7. On every change to the document, regenerate, run the tests, and read the diff of the generated code during review: it shows exactly which consumers are affected.

Expected result

The OpenAPI document changes first and code follows mechanically; a contract change that would break a consumer surfaces as a compile error or a generated-code diff rather than at runtime.

Limits and test basis

Generators cover the common subset of the specification; complex oneOf schemas, callbacks and unusual security schemes may produce awkward or wrong code, and the generator's own issue list becomes part of the dependency. Generated code is verbose; the volume is the price of the contract. The procedure is a synthesis of the cited documentation, not a measured comparison.