From 0.X Series to 1.X Series
Apigentools major version 1 is somewhat different from the 0.X series. It reflects the experience obtained by the apigentools developers through several months of using apigentools 0.X.
Before apigentools 1.X release, there were two ways to run apigentools - in container or outside of a container. While this allowed for reproducibility by pinning the container tag/sha, it had its own problems:
- It didn't allow for detaching of openapi-generator version used from apigentools version used when using containerized version.
- It didn't allow for (easily) using different versions of openapi-generator to generate different libraries/major spec versions for libraries.
- It didn't allow for using different code generating tools, such as restful-react.
- It required building and maintaining custom image to achieve any of the above. The alternative was using a local environment that would be hard to reproduce among developers of a single Spec Repo.
- It posed problems with passphrase protected SSH keys and handling them inside used container.
- And more...
Apigentools 1.X takes a different approach described in sections below.
Apigentools 1.X code is expected to run outside of container, while executed subprocesses (which are considered to be environment specific) run in containers.
openapi-generator No Longer Built In
openapi-generator, while still the default code generation tool, is not required. A different code generation tool might be used by providing a custom command.
Overriding Container Options for Commands
Each command is executed in an individual container and can use a different environment for the container, including specification of individual image. This is achieved through the container_opts argument that can be specified on multiple levels of the configuration and implements simple inheritance.
Detaching Code Generation Process of Major API Versions for Languages
The new config file syntax allows specifying different ways to generate code for different major API versions for a single language, including usage of different pre/post commands, different generation command, different template patches.
Spec Repo structure
Template preprocessing is now configured in the configuration file, including specifying the templates source, list of template patches (and their order, which is implied by their position in the list).
Apigentools no longer automatically searches for Dockerfiles to build and run tests in. There is now a
tests section in the configuration file where you can define a list of commands that constitute tests.
New Configuration File Syntax
The configuration file now uses Yaml as a markup language. It's been overhauled to support the above usecases, but should look very familiar to existing apigentools users.
Default Spec Sections
Apigentools 1.X code doesn't have any special treatment for
spec/<version>/shared.yaml files. While they are stil recommended for
servers/... resp. shared components, they have to be explicitly listed in