PR checklist
-
Read the contribution guidelines. -
Ran the shell script under ./bin/to update Petstore sample so that CIs can verify the change. (For instance, only need to run./bin/{LANG}-petstore.sh,./bin/openapi3/{LANG}-petstore.shif updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in.\bin\windows\. If contributing template-only or documentation-only changes which will change sample output, be sure to build the project first. -
Filed the PR against the correct branch: master,4.1.x,5.0.x. Default:master. -
Copied the technical committee to review the pull request if your PR is targeting a particular programming language.
Description of the PR
This is general enhancements as part of the Separation of Concerns project, and is work toward moving things to a Core package (#845). In doing so, my goal is to separate conceptual responsibilities of our internal implementations.
This PR leaves CodegenConfigurator as an "entrypoint" to configuring internals. There's still some work to be done to simplify that interface so we may remove redundant code from CLI, Maven Plugin, Gradle Plugin, and openapi-generator-online (which duplicates much of CodegenConfigurator in Generator.java).
A potentially minor breaking change, I've removed all getters from CodegenConfigurator. The caller already knows the properties being set on this type, and any evaluation should be done after calling toClientOptInput or the new toContext.
This PR introduces two new types: GeneratorSettings and WorkflowSettings. These are intentionally immutable, which will aid in testing once they are applied to a generator instance (generator authors can evaluate input settings against modified settings to validate any transformations done in the generator). These types are separate so we can clearly differentiate between those settings defining the what (generator outputs) versus the how (the workflow taken to generate outputs).
As part of creating these new Settings types and moving to make CodegenConfigurator more SOLID, I've also introduced a DynamicSettings type which handles the deserialization of those settings which were previously considered CodegenConfigurator. Now, CodegenConfigurator is simply orchestrating how we configure everything in preparation for generation. DynamicSettings doesn't live in the Core module because it relies on Jackson JSON, and there's technically no need for this to live in a user-consumable module (users can just set additional properties directly); loading the config from file is application-specific.
While focusing on this settings cleanup, I wanted to rename GeneratorProperties to avoid confusion with GeneratorSettings. The intention is that GeneratorSettings are those settings which are applied to a generator (an instance of CodegenConfig). GeneratorProperties, on the other hand, is a way to access System properties and modify them on a thread local to avoid race conditions during CI or other workflows… so I've opted to rename this to GlobalSettings. GlobalSettings will therefore be anything that can be considered outside the responsibility of a generator or its workflow (e.g. debugModels could be set as a System Property and used by either). We recently had a report of -D options not making it down to swagger-parser (see #2706 (closed)), and this is because the CLI has a custom argument of -D which can easily be confused as the Java property -D. In this PR, I've added a deprecation warning with instructions to stop using the -D argument to generate and move this option to System properties. If we find that something like -DdebugModels or other supported "system properties" currently cause conflicts elsewhere, we may want to add a new global-settings option. I didn't do this in this PR because it seemed like a little too much for a single change.