apigentools CLI Reference
Basic usage:
apigentools <apigentools-args> <SUBCOMMAND> <subcommand args>
Note that a lot of arguments can take their value from environment variables and coded-in defaults. In this case, the actual value is obtained like this:
- If the commandline argument is provided, it is used.
- If the commandline argument is not provided and the environment variable exists, its content is used.
- If the commandline argument is not provided and the enviromnent variable doesn't exist, the coded-in default is used.
Throughout this document, arguments with this behaviour have a value both in their "Environment Variable" column as well as in their "Default" column.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-av API_VERSIONS, --api-versions API_VERSIONS |
The API version to run the specified action against. These must match what the config in the spec repo contains. Example: apigentools -av v1 -av v2 test |
APIGENTOOLS_API_VERSION |
None to run against all |
-c CONFIG_DIR, --config-dir CONFIG_DIR |
Path to config directory | APIGENTOOLS_CONFIG_DIR |
config |
-g GENERATED_CODE_DIR, --generated-code-dir GENERATED_CODE_DIR |
Path to directory where to save the generated source code | APIGENTOOLS_GENERATED_CODE_DIR |
generated |
-h, --help |
Show help message and exit | ||
-l LANGUAGES, --languages LANGUAGES |
Languages to run the specified action against. These must match what the config in the spec repo contains. Example: apigentools -l go -l java test |
APIGENTOOLS_LANG |
None to run against all |
-r SPEC_REPO_DIR, --spec-repo-dir SPEC_REPO_DIR |
Switch to this directory before doing anything else | APIGENTOOLS_SPEC_REPO_DIR |
. |
--git-via-https |
Whether to use https (or ssh) for git actions | APIGENTOOLS_GIT_VIA_HTTPS |
false |
--git-via-https-installation-access-token |
Use installation access token (authenticating a Github app) for git actions. Mutually exclusive with --git-via-https-oauth-token . |
APIGENTOOLS_GIT_VIA_HTTPS_INSTALLATION_ACCESS_TOKEN |
|
--git-via-https-oauth-token |
Use OAuth over HTTPS passing this token for git actions. Mutually exclusive with --git-via-https-installation-access-token . |
APIGENTOOLS_GIT_VIA_HTTPS_OAUTH_TOKEN |
|
-v, --verbose |
Whether or not to log the generation in verbose mode |
apigentools generate
Generates client code. When specified with the --clone-repo
flag, the generated-code-dir
for that client must be empty.
Argument | Description | Environment Variable | Default |
---|---|---|---|
--additional-stamp [ADDITIONAL_STAMP [ADDITIONAL_STAMP ...]] |
Additional components to add to the apigentoolsStamp variable passed to templates |
APIGENTOOLS_ADDITIONAL_STAMP |
[] |
--builtin-templates |
Use unpatched upstream templates | false |
|
-d DOWNSTREAM_TEMPLATES_DIR, --downstream-templates-dir DOWNSTREAM_TEMPLATES_DIR |
Path to directory with downstream templates | APIGENTOOLS_DOWNSTREAM_TEMPLATES_DIR |
downstream-templates |
-f FULL_SPEC_FILE, --full-spec-file FULL_SPEC_FILE |
Name of the OpenAPI full spec file to write | APIGENTOOLS_FULL_SPEC_FILE |
full_spec.yaml |
-h, --help |
Show help message and exit | ||
-i GENERATED_WITH_IMAGE, --generated-with-image GENERATED_WITH_IMAGE |
Override the tag of the image with which the client code was generated | APIGENTOOLS_IMAGE |
None |
-s SPEC_DIR, --spec-dir SPEC_DIR |
Path to directory with OpenAPI specs | APIGENTOOLS_SPEC_DIR |
spec |
-t TEMPLATE_DIR, --template-dir TEMPLATE_DIR |
Path to directory with processed upstream templates | APIGENTOOLS_TEMPLATES_DIR |
templates |
--clone-repo |
Whether to clone the client Github repositories before running code generation | APIGENTOOLS_PULL_REPO |
False |
apigentools init
Initializes a new Spec Repo.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-g, --no-git-repo |
Don't initialize a git repository in the project directory | ||
-h, --help |
Show help message and exit |
apigentools push
Pushes the content of the generated directory to its target git repository The generated directory is left in the branch that was checked out to push the code.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-h, --help |
Show help message and exit | ||
--default-branch |
Default branch of client repo - if it doesn't exist, it will be created and pushed to instead of a new feature branch | APIGENTOOLS_DEFAULT_PUSH_BRANCH |
master |
--dry-run |
Do a dry run (do not actualy create branches/commits or push) | False |
|
--push-commit-msg |
Commit message to use when pushing the generated clients. | APIGENTOOLS_COMMIT_MSG |
Regenerate client from commit <XYZ> of spec repo |
--skip-if-no-changes |
Skip committing/pushing for all repositories where only .apigentools-info has changed |
APIGENTOOLS_SKIP_IF_NO_CHANGES |
False |
--git-email |
Email of the user to author git commits as | APIGENTOOLS_GIT_AUTHOR_EMAIL |
None |
--git-name |
Name of the user to author git commits as | APIGENTOOLSGIT_AUTHOR_NAME |
None |
Note Specifying the --git-*
flags will modify the .git/config settings of each local repository pushed to via apigentools. This will not modify the global .git/config.
apigentools split
Splits an existing one-file OpenAPI spec into multiple sections suitable for usage with apigentools. Useful when doing a first-time batch import of an already existing spec.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-h, --help |
Show help message and exit | ||
-i INPUT_FILE, --input-file INPUT_FILE |
Path to the OpenAPI full spec file to split | ||
-s SPEC_DIR, --spec-dir SPEC_DIR |
Path to directory with OpenAPI specs | APIGENTOOLS_SPEC_DIR |
spec |
-v API_VERSION, --api-version API_VERSION |
Version of API that the input spec describes | APIGENTOOLS_SPLIT_SPEC_VERSION |
v1 |
apigentools templates
Obtains upstream openapi-generator templates, applies template patches and saves them to templates directory.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-h, --help |
Show help message and exit | ||
-o OUTPUT_DIR, --output-dir OUTPUT_DIR |
Path to directory where to put processed upstream templates | APIGENTOOLS_TEMPLATES_DIR |
templates |
-p TEMPLATE_PATCHES_DIR, --template-patches-dir TEMPLATE_PATCHES_DIR |
Directory with patches for upstream templates | APIGENTOOLS_TEMPLATE_PATCHES_DIR |
template-patches |
apigentools templates local-dir
Obtains upstream templates from a given local directory.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-h, --help |
Show help message and exit |
Positional Argument | Description | Environment Variable | Default |
---|---|---|---|
local_path |
Path to directory with openapi-generator upstream templates |
apigentools templates openapi-git
Obtains upstream templates from openapi-generator git repository.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-h, --help |
Show help message and exit | ||
-u REPO_URL, --repo_url REPO_URL |
URL of the openapi-generator repo | https://github.com/OpenAPITools/openapi-generator |
Positional Argument | Description | Environment Variable | Default |
---|---|---|---|
git_committish |
Git 'committish' to check out before obtaining templates | master |
apigentools templates openapi-jar
Obtains upstream templates from an openapi-generator jar file.
Argument | Description | Environment Variable | Default |
---|---|---|---|
-h, --help |
Show help message and exit |
Positional Argument | Description | Environment Variable | Default |
---|---|---|---|
jar_path |
Path to openapi-generator jar file | APIGENTOOLS_OPENAPI_JAR |
openapi-generator.jar |
apigentools test
Runs tests of generated clients.
Argument | Description | Environment Variable | Default |
---|---|---|---|
--container-env [CONTAINER_ENV [CONTAINER_ENV ...]] |
Additional environment variables to pass to containers running the tests, for example --container-env API_KEY=123 OTHER_KEY=234 . Note that apigentools contains additional logic to treat these values as sensitive and avoid logging them during runtime. (NOTE: if the testing container itself prints this value, it will be logged as part of the test output by apigentools). |
||
-g GENERATED_CODE_DIR, --generated-code-dir GENERATED_CODE_DIR |
Path to directory where the generated source code is | APIGENTOOLS_GENERATED_CODE_DIR |
generated |
-h, --help |
Show help message and exit | ||
--no-cache |
Build test image with --no-cache option | APIGENTOOLS_TEST_BUILD_NO_CACHE |
False |
Containerized Version
The apigentools PyPI package ships with two scripts - apigentools
and container-apigentools
. The containerized version will execute all commands in a container created from given image. Additionally, all APIGENTOOLS_*
environment variables from current environment are passed inside the container. Basic usage:
container-apigentools IMAGE [--spec-repo-volume SPEC_REPO_VOLUME] [APIGENTOOLS_ARG ...]
Argument | Description | Environment Variable | Default |
---|---|---|---|
--spec-repo-volume SPEC_REPO_VOLUME |
Path to directory with the Spec Repo | . |
Positional Argument | Description | Environment Variable | Default |
---|---|---|---|
IMAGE |
apigentools image to use, e.g. apigentools:1.2.3 |
||
APIGENTOOLS_ARGS |
arguments to pass to apigentools running inside container, see the help for apigentools above |
Note that if APIGENTOOLS_ARGS
is not provided, a full automated workflow will be run.