OAS 3.x specification isn't entirely clear on oneOf support. JSON Schema
defines oneOf in such a way that the Schema is only valid if it
validates against exactly one of the referenced Schemas. This suggests
that a Schema defined with oneOf can't include additional "dynamic"
properties. OpenAPI extends on this by adding the necessary
discriminator object, which allows tooling to decide the intended
Schema.
As tooling, openapi-generator may support loose or confusing definitions
in the Specification to better support our user's use cases. In this
case, we may warn that while this usage is technically valid the two
target specifications are unclear about the actual constraints regarding
oneOf.
* [cli][batch] Better glob support
If invoked as `openapi-generator batch *.yaml`, the command might
previously fail in some shells where `*.yaml` expands to file name only.
This supports globs without path-part in the filename to prevent
possible NPE.
* [cli] Document batch command
* [meta] Support Kotlin meta generator
* Guard against automatic scripts (assumptions for this script are not fulfilled by some CI which run "run all" type scripts)
* [docs] Updating docsite outputs to be browsable on Github as well
* Fix links to other files
Suffix `.md` was needed to make links works
* [docs] Add clarification to differences between customization and templating docs
* [docs] Collapsible side bar, scroll to top, minor enhancements
* [CLI] Initial implementation for batch generation
Allows for generating multiple outputs via config. Just specify multiple
config files on command line.
Intent for this is to reduce CI times to generate outputs as well as to
reduce time for users to run ensure-up-to-date to meet PR standards.
Example command:
openapi-generator batch --includes-base-dir `pwd` --fail-fast -- bin/ci/*
---
As part of this implementation, the batch command support a customized
JSON key, `!include`. If this key's value refers to an existing file,
that file's contents are "unwrapped" into the config during
deserialization. This allows us to easily point to the same configs used
by our sample scripts without modifying the CLI generate task's switches
or assumptions.
* Allow for path-relative outputs
* Add batch JSON objects
* Include INFO log about threads used and includes/root
* Ensure GlobalSettings.reset()
* Improved thread-safety of ModelUtils
* Filter deprecated generators from CLI list by default.
* [gradle] Exclude deprecated generators from list by default, add "include" option to allow for customization of list task.
* Update scripts to support the --include option of the list command
* Update gradle/cli docs for generators listing with "include" option.
* [core] Initial support for server variable overrides
* [gradle] Support user overrides for serverVariables
* [core] Clarify server variable overrides, and propagate them to templates in the "servers" array
* Introduce GeneratorSettings + cleanup
GeneratorSettings is an immutable settings object, intended to limit the
manipulation of generator settings.
To move to GeneratorSettings, lots of modification was done to
CodegenConfigurator. The goal here is that CodegenConfigurator
would create the contextual information required to initiate a
generator run:
* GeneratorSettings
* Workflow related settings
* Configuring "system" GeneratorProperties (ThreadLocal properties)
* Deserializing from file to config object
* Input spec document (OpenAPI, intending to target others)
ClientOpts was generally unused, and the few places it was being used
have been updated to pass the properties to
codegen.additionalProperties.
* Add sanity to system properties
The -D argument for the generate command is an application argument
which is easily confused for Java System Properties. This isn't the
case, as setting values here doesn't update the configuration in
System.getProperties().
This adds a warning and deprecation to that option, as defining these
values as system properties will also continue to work as expected. This
makes the -D application argument redundant and confusing.
* Contextualize generator/workflow settings
This splits settings relevant to generator configuration (the what) and
workflow configuration (the how) in an attempt to make configuration
easier to conceptualize.
* Update Gradle task w/ CodegenConfigurator setters
* Remove -D usage in scripts
* Add -p option for additional properties
* Regnerate samples
* [feat] Intro GeneratorMetadata (stability index)
GeneratorMetadata offers an immutable object created via Builder pattern
which allows generators to explicitly define their stability (stable,
beta, experimental, deprecated) as well as a message to be shown during
generation.
This is a step toward:
* Fleshing out the "Core" artifact (#845)
* Providing a place to encapsulate feature-oriented metadata (#840)
* Providing a means to communicate end of life scheduling (#116)
This new structure, specifically the Stability property, allows us to
offer future enhancements such as allowing users to filter down to only
"Stable" generators via CLI, and eventually any compat table (see #503).
* Mark deprecated generators as deprecated in-code
* Re-export docs/generators.md
* [all] Adds strict spec option
Introduces an option to allow user customization of strict specification
behaviors. For instance, OpenAPI 3.x requires a path object name to be
prefixed with '/' so we append any missing '/', but this may not be
desirable to some users or generators. In this commit, this fix specifically is
the only modification affected.
* Clarify strict-spec docs, add option to README.md
* Update CLI options in docs/usage.md
* [cli] Support packageName as global option
CLI supports other package-related options (--api-package,
--model-package, --invoker-package). This aligns those options with
--package-name to avoid confusion about how to configure these options
where those are supported.
This intentionally does not apply a packageName getter/setter to
DefaultCodegen to reduce the footprint of this change.
* [gradle] Add packagName as global option
This makes packageName available as a global option, beside apiPackage,
modelPackage, and invokerPackage to reduce potential confusion about how
to configure the four of these options by generators which support them.
* new module: openapi-generator-core
* templating engine adapters to support extension (currently only Handlebars)
* new `-e` templating engine CLI option
* adapt Generator to process Template with the passed TemplatingEngineAdpater
* add a MustacheEngineAdapter to the codegen in the unit tests
* force default MustacheEngineAdapter
* copy new core module in the root Dockerfile
* add processTemplatingEngine to CodegenConfig, to be overriden by Codegen classes if needed
* support multiple file extensions per templating engine adapter
* Extends handlebars experimental adapter with explicit contextual resolvers (e.g. map processing)
* Add new openapi-generator-core/pom.xml to release_version_update.sh
* A detailed message will be logged on missing handlebars helper
* Adds README documentation around template default and beta options
* Moves mustache package under new templating package
* Include built-in handlebars helpers which require explicit registration, and custom `startsWith` helper.
* 2nd attempt to make the automatic checkin testing work
* trying to submit the samples in hopes that the CI matches them and passes
* found some samples I hadn't updated. Maybe this is it?
* Iniital docusaurus based site
* Remove error about default local being used by String.format
* Change pinned users to represent global presence rather than alphabetical order pinning
* Include generator indexes in ensure-up-to-date (docusaurus site and /generators/README)
* Add Font Awesome attribution footer
* Remove feature callout until it is completed
* Include NPM try it out section
* Improve "Getting Started" type docs
* Include new custom template documentation
* Updating templating and customization docs
* Add vendor extension docs
* Cleanup templating page(s).
* Move users to yaml file for easy edit.
* travis configuration, and baseUrl mods to image URLs
* [docs] Migrate FAQ, release summary from wiki
FAQ has been split into multiple smaller documents to better categorize
and allow users to find what they're looking for (in docs folder or in
new website).
Release summary information (versioning strategy and cadence) has been
migrated from the Wiki and clarified a bit.
Also adds copy button for all code snippets in website.
* Copy current contributing/code of conduct to website
* [docs] Creating a new generator
* Clean up file output handling
This attempts to normalize all generators to use OS agnostic
File.separator.
It also cleans up some areas in code where we replace "." in full file
output path with File.separator. We should only be modifying directory
names we own, and should avoid modifying anything that can be provided
by a user.
It would probably be better to use Paths.get(…).toString() in all cases.
* Fix missed path separators in java codegen
* Adjust Java codegen path replacements
* Convert / in full path replacements, as / is forbidden in Windows, and noop elsewhere
* Use Paths.get where files are written, to better handle Windows path constraints
This updates config-help to have more control over how the output is
written for the user. We dump config-help output for per-generator
documentation, and this cleans up some cross-platform compatibility
issues that might arise from tweaking the output for clarity in the
target file.
Previously, we'd pipe config-help output to sed, then insert the
generator name, which we then redirected to an output file. The sed
syntax had to include a trailing newline so our tabbed configs would
automatically become code tags in markdown. Inserting newlines into sed
replacement strings doesn't work the same across platforms, mostly
because of Apple's customizations to GNU programs.
This commit moves the generator name and newline insertion into the
command itself. It also includes a new --output option, allowing the
user to specify the output location of the config-help.
Currently, we only dump in plain-text, and it is only coincidental that
our plaintext output results in a desirable Markdown output. If
tabbed lines did not automatically convert to a code style block, some
generators like C# would end up with broken text (`List<T>` would become
just `List`, for example).
I had previously discussed extending config-help to output to other
formats like asciidoc. This commit does not introduce any steps toward
that end.
* Added forbiddenapis check and fixed the findings in the normal code
* Fixed forbiddenapi findings in java templates and samples.
* Generated all samples for Java.
It makes sense that error messages should be written to STDERR and
all others should be written to STDOUT (as shown in #207). However, it
would be convenient to parse the debugging output when the relevant
flags are set.
This change will disable logging to STDOUT and redirect all log messages
to STDERR when any of the debug flags are set. (Resolves#473)
* Validate spec on generation by default
Adds a validation parameter to CodegenConfigurator, and passes through
options from CLI, Maven Plugin and Gradle Plugin to that property.
Default is to validate the spec during generation. If spec has errors,
we will output errors as well as warnings to the user.
Option can be disabled by passing false to validateSpec (Maven/Gradle)
or --validate-spec (CLI).
* Prepare version 3.1.1-SNAPSHOT
* fix version
* Use last prod version for the sample
* Update README.md
Fix
* [cli] Option parser does not support true/false for boolean options
* [cli] Completions command for suggestions
This takes airlift's 'suggest' command and reuses it as a different
command name, 'completion'. This gives us in-built CLI completions which
are useful in the repo-level container's docker-entrypoint.sh. This
previously parsed Java files for conventional usage of Command
annotations, which is potentially buggy. The new implementation relies
only on CLI to provide command completion suggestions.
As part of this, we can prepare for bash completion scripts which can be
added to our homebrew formula. The new completion command will also
complete on command options, for example:
cli completion generate
This will provide all short and long form switches available to the
generate command.
* Add piggyback license onto licensed of file borrowed from airlift/airline
* [cli] Write to stdout/stderr, allow redirection
Previously, slf4j-simple from generator core was being used. This writes
to only a single stream (STDERR) and is confusing from a CLI tooling
perspective.
This consumes logback in CLI, and excludes core's slf4j-simple
dependency. This allows us to define multiple appenders, one for STDOUT
and one for STDERR.
WARN messages and lower are written to STDOUT. ERROR is written to
STDERR.
* [cli] Limit logs to match prev implementation
* Remove slf4j-simple from core project, to avoid conflicts with consumer logger implementations
* Errors in Generate/Validate print to stderr/exit 1
Generate and Validate exposed exceptions rather than user-friendly
messages when an error occurred. In generate, this could happen for
numerous reasons, but the most likely is a user typing (or guessing) an
invalid generator name. In Validate, an error was exposed if there were
any validation errors in a spec.
New behavior:
* Generate now exposes a typed exception when a generator cannot be
loaded by name. This allows consistent messaging for load failures.
* Generate now presents guidance on failure (check the spelling and try
again). This is purely a usability improvement.
* Validate now writes validation errors to stderr and exits with code 1.
* Improve err messages: config-help/required opts.
config-help now presents same error for invalid generator names as the
'generate' command.
Options which are required, and those which require a value, now present
a user-friendly hint at the error and exit with code 1 (rather than an
uncaught exception).
* Log missing -g error to stderr rather than LOGGER
Co-authored-by: Akihito Nakano <sora.akatsuki@gmail.com>
Co-authored-by: Jeremie Bresson <dev@jmini.fr>
Co-authored-by: Jim Schubert <james.schubert@gmail.com>
Co-authored-by: Martin Delille <martin@phonations.com>
Co-authored-by: Tomasz Prus <tomasz.prus@gmail.com>
Co-authored-by: William Cheng <wing328hk@gmail.com>
