Package: ibm-apidocs-cli
This tool allows users to generate the api documentation.InstallationInstall the CLI withpiporeasy_install:pipinstall-Uibm-apidocs-clioreasy_install-Uibm-apidocs-cliClone acloud-api-docsrepo to a local directory. Make sure the repo contains the requiredapiref-index.jsonfile and the front-matter configuration file
(typically<openapi>-config.json).Configure your GitHub Enterprise access token. You can skip this step
if you do not want the CLI to automatically download the latest
front-matter and SDK generator code.Follow these steps:Get an access token fromGitHub
Enterprise. For more
information, see theGitHub
help.Set theGITHUB_TOKENenvironment variable:export GITHUB_TOKEN=<token>Optional:Configure a public GitHub access token. The CLI uses
the GitHub API to retrieve the latest SDK versions. If you encounter
errors caused by exceeding the GitHub API rate limit on anonymous
requests, try configuring the public GitHub access token.Follow these steps:Get an access token fromGitHub. For more
information, see theGitHub
help.Set theGITHUB_PUBLIC_TOKENenvironment variable:export GITHUB_PUBLIC_TOKEN=<token>Optional:Clone thefrontmatter
generatorto a local directory. If you do not have a local clone of the
front-matter generator repo, the CLI will automatically clone it to a
temporary directory.Optional:Install theSDK
generatorto a local directory. If you do not have a local copy of the SDK
generator, the CLI will automatically download the latest version to
a temporary directory.To install the SDK generator, you do not need to clone or download the
full repository or build the project. Instead, use theinstaller.
For more information, seethe generator
README.Note:The SDK generator .jar file must be namedopenapi-sdkgen.jar. If you have downloaded or built a version of the
file with a different name (e.g.``openapi-sdkgen-<version>.jar``), you
must rename it.UsageThere are two distinct modes of usage:Manual modeis used to process a single API definition, using a
local clone of thecloud-api-docsrepo for the service. This mode
offers fine-grained control, with command-line arguments to specify
the front-matter config file and templates, the output location, and
other options that are specific to the file being processed. Any
required information that is not specified (other than the input API
definition) is looked up from thegenerate-apidocs.jsonmap file.
Manual mode is the default.Batch modeis used to process one or more API definitions,
specified either individually or using wildcards. With batch mode,
processing is largely driven by the map file, which determines the
file-specific options for each API definition. You can use optional
command-line arguments to specify global options such as the SDK
generator to use or the target directory wherecloud-api-docsrepos are located. Batch mode is specified using the--batchor-bargument.Syntaxusage: ibm-apidocs-cli [-h | --help]
                       [--batch | -b]
                       -i <input_openapi> | --openapi <input_openapi>
                       [--config <config_file>]
                       [--mapfile <map_file>]
                       [--apidocs <apidocs_path>]
                       [--templates <templates_path>]
                       [--examples <examples_path>]
                       [--output_folder <output_path>]
                       [--target <target>]
                       [--frontmatter <frontmatter_path>]
                       [--sdk_generator <sdk_generator_path>]
                       [--sdkgen_release <sdkgen_release>]
                       [--commit_msg <commit_message>]
                       [--skip_sdkgen] [--push] [--keep_sdk] [--keep_temp]
                       [--no_update] [--verbose] [--version]Required arguments:-i,--openapi<openapi_file>: The path to the input OpenAPI
definition file(s) to process:In manual mode, this must be exactly one file (for example,assistant-v1.json).In batch mode, this can be one or more file names or patterns,
separated by spaces. Any pattern containing wildcards will be
expanded. For example,./apis-public/*.json./apis-private/*data*.jsonwould process all
files in theapis-publicsubdirectory and all files matching the
pattern*data*.jsonin theapis-privatesubdirectory.Note:If you specify a path that contains wildcards, do not
surround it with quotation marks. Use a backslash (\) to escape
spaces in the path.Only files that are defined in the mapping file are processed. Any file
not in the mapping file is skipped, and processing continues.Optional arguments:-h,--help: Display usage information.-b,--batch: Batch mode switch. Use batch mode to process
multiple files at once, using the map file to automatically look up
required values on a per-file basis. The default is manual mode,
which offers more fine-grained control over options but can process
only one file at a time.Note:The handling of some command-line arguments, as well as which
arguments are valid, differ between batch mode and manual mode, as
described in this document.--config<config_file>(Manual mode only): The front-matter
config file (e.g.assistant-v1-config.json). You can optionally
specify the full path to the config file; if you do not include the
path, the file is assumed to be in theapidocsdirectory. If you
do not specify the config file, the file name is looked up from the
map file, and the file is assumed to be in theapidocsdirectory.In batch mode, the config file name is always looked up from the map
file and retrieved from the downloadedcloud-api-docsrepo for the
service.--apidocs<apidocs_path>(Manual mode only): The path to thecloud-api-docsrepository or other directory containingapiref-index.jsonand front matter config file. If you do not
specify this argument, the current directory is used. In batch mode,
you can use the--targetargument to use localcloud-api-docsrepos.--templates<templates_path>(Manual mode only): Path to the
directory containing the front-matter templates to use. You can
specify either an absolute path or just the directory name (for
example,templates-data); if you specify just the directory name,
it is assumed to be a subdirectory of the front-matter generator
location. If you do not specify a templates directory, the CLI will
use the templates directory specified in the map file.In batch mode, the templates directory for each API definition is looked
up from the map file.--examples<examples_path>Path to the directory containing the
example files associated with the input OpenAPI definition(s). This
is typically theexamplesdirectory of a local clone of thedeveloper-cloud--api-definitionsrepo). If you do not specify an
examples directory, the CLI will download the example files from thedeveloper-cloud--api-definitionsGHE repo. In batch mode, the
same examples directory is used for all API definitions.The specific example files to be copied to the output directory for a
given OpenAPI file are listed in the map file. If theexamplesarray
is empty or absent for the input API definition, no example files are
copied.--output_folder<output_folder>(Manual mode only): The output
directory for generated files. If you do not specify this argument,
output files are written to the current directory. In batch mode, you
can use the--targetargument to control the location for
generated files.--target<target>(Batch mode only): The parent directory of
the localcloud-api-docsrepos you want to use for config files
and output. The CLI will look for subdirectories of this directory
named according to the service names listed in the map file, which
correspond to thecloud-api-docsrepo names (for example,watson-assistantordiscovery). If the expected subdirectory
is not present, the CLI will clone it from GHE.Important:If thecloud-api-docsdirectory for an affected
service already exists as a subdirectory of thetargetlocation, the
CLI uses it as-is. The config file might be modified, and the generated
files will overwrite previous versions that are already present. Keep in
mind that if this directory is not current, you might not be able to
push the changes to GHE without conflicts. It is your responsibility to
make sure any existingcloud-api-docsdirectories are current, or
that they contain only changes you want. (You can also delete any
existingcloud-api-docsdirectory and allow the CLI to clone the
current version from GHE.)If you omit the--targetargument in batch mode, thecloud-api-docsdirectories for the affected services are cloned to a
temporary location. This means that the output is discarded after
processing completes (unless you specify the--keep_tempargument).
This can still be useful if you want to run a test build to check for
build errors, but do not need to see the generated output.--mapfile<map_file>: The path to a local map file, including
file name (for example,generate-apidocs.json). If you do not
specify a local map file, the current map file is downloaded from thedeveloper-cloud--api-definitionsrepo as needed.--frontmatter<frontmatter_path>: Path to the directory
containing the front-matter generatorapp.jsfile. Use this
option if you need to use a specific version or branch of the
front-matter generator code, or if you do not have a GitHub access
token configured. If you do not specify a location, the CLI will
automatically clone the latest version of the front-matter generator
repo to a temporary directory and use that clone.--sdk_generator<sdk_generator_path>: Path to the directory
containing the SDK generator JAR file, optionally including the file
name. If you specify a directory but not a file name, the JAR file is
assumed to beopenapi-sdkgen.jar. Use this option if you need to
use local copy of the SDK generator. If you do not specify this
parameter, the CLI will automatically download the theopenapi-sdkgen.jarfile to a temporary directory and use that
copy.--sdkgen_release<sdkgen_release>: Release of the SDK generator
to download, if you are allowing the CLI to download the generator
automatically. Specify the GitHub release tag (for example,1.0.0.1). If you do not specify a release, the CLI uses the most
recent maintenance release for the major release specified in the map
file. This argument is ignored if--sdk_generatoris specified.--commit_msg<commit_message>:(Batch mode only)Custom commit
message to use when pushing generated files to thecloud-api-docsrepo for the service. (Ignored if--pushis not also specified.)
If you do not specify a custom commit message, the default commit
message isCommit byibm-apidocs-cli:build <oas3_file>.--skip_sdkgen: Skips the generation of SDK-specific JSON files
using the SDK generator. Use this option to speed processing if you
only want to update the front matter or example files. For example,
you might use this option if the API definition has not changed, but
you want to update the front matter or examples.Important:The
input API definition file is always copied to the output or target
directory, even if you specify--skip_sdkgen. If the API
definition has changed, this could cause mismatches with any existing
SDK-specific files.--push:(Batch mode only)Commit and push generated files to
themasterbranch of the remote GitHubcloud-api-docsrepo
for the service.Important:This feature uses thegit add,git commit, andgit pushcommands to push the local target directory (where files
are generated) to GitHub. If you are using the--targetargument to
generate files in an existing local directory, that directorymustbe
an up-to-date valid local clone of a remote api-docs repo, with themasterbranch checked out.The safest way to use the--pushoption is to omit the--targetargument. This ensures that the generated files are written to a freshly
cloned local repo, which is guaranteed to be even with the remote.--keep_sdk: Preserve the_sdktempdirectory containing
generated SDK artifacts. Useful for debugging purposes.--keep_temp: Preserve the temporary directory containing the
downloaded front-matter and SDK generators, as well as anycloud-api-docsrepos downloaded during batch processing. Useful
for debugging purposes.--no_update: Use front-matter config file as-is without updating
SDK versions. If you do not specify this argument, the config file is
updated with the latest GitHub release for each supported SDK
language.-h,--help: Show usage information and exit.--verbose: Verbose flag.--version: Show program’s version number and exit.Example commands: manual modeThis example assumes that the command is being run from theapidocsrepo directory containing the API Reference files, and that the CLI is
automatically downloading and using the latest code for the front-matter
and SDK generators. All output files are written to the current
directory:ibm-apidocs-cli-iassistant-v1.jsonThis example uses different locations for the input and output files,
and also specifies local copies of the SDK generator and front-matter
generator code:ibm-apidocs-cli -i '/Users/my_user/Documents/GitHub/api-apidocs-cli/test/resources/config/assistant-openapi3-v1.json' \
                -c '/Users/my_user/Documents/GitHub/api-apidocs-cli/test/resources/config/test-input-config.yaml' \
                --output_folder '/Users/my_user/Documents/GitHub/api-apidocs-cli/test/target' \
                --frontmatter '/Users/my_user/Documents/GitHub/frontmatter-generator' \
                --sdk_generator '/Users/my_user/Documents/Release/openapi-sdkgen/lib'Example commands: batch modeThis example builds two API definitions from the current directory. All
other required files, including the map file, thecloud-api-docsrepo, the front-matter generator, and the SDK generator, are downloaded
automatically. Output is written to the temporarycloud-api-docsdirectory and is not kept.ibm-apidocs-cli -b -i assistant-v1.json assistant-v2.jsonThis example builds all API definitions from thepublicandprivatesubdirectories, using local copies of thecloud-api-docssubdirectories for the affected services. Generated files will be
written to these same subdirectories.ibm-apidocs-cli -b ./apis-public/*.json ./apis-private/*.json --target ~/github/cloud-api-docsMapping fileThegenerate-apidocs.jsonmapping file is a configuration file that
is used byibm-apidocs-clito determine various default values for
each API definition.The canonical version of this file is located in the root of thedeveloper-cloud–api-definitionsrepo. By default, the CLI downloads and uses the current mapping file
from GitHub, but you can use the--mapfileargument to specify a
local mapping file.The format of the mapping file is as follows:{
  "name": "api-mapping",
  "version": "0.1.0",
  "sdkgen_major_release": "2",
  "description": "api document mapping used by ibm-apidocs-cli tool",
  "public": [
    {
      "service": "watson-assistant",
      "openapi": "assistant-v1.json",
      "config": "assistant-v1-config.json",
      "frontmatter": "templates",
      "examples": [
        "assistant-v1-curl-examples.json",
        "assistant-v1-dotnet-standard-examples.json",
        "assistant-v1-go-examples.json",
        "assistant-v1-java-examples.json",
        "assistant-v1-node-examples.json",
        "assistant-v1-python-examples.json",
        "assistant-v1-ruby-examples.json",
        "assistant-v1-swift-examples.json",
        "assistant-v1-unity-examples.json"
      ]
    },
    ...
  ],
  "private": [
    {
      "service": "watson-assistant",
      "openapi": "assistant-data-v1.json",
      "config": "assistant-v1-config.json",
      "frontmatter": "templates-data",
      "examples": [
        "assistant-v1-curl-examples.json",
        "assistant-v1-dotnet-standard-examples.json",
        "assistant-v1-go-examples.json",
        "assistant-v1-java-examples.json",
        "assistant-v1-node-examples.json",
        "assistant-v1-python-examples.json",
        "assistant-v1-ruby-examples.json",
        "assistant-v1-swift-examples.json",
        "assistant-v1-unity-examples.json"
      ]
    },
    ...
  ]
}where:name: An identifier for the mapping file. This value is not used
by the CLI.version: The mapping file version. This value is not used by the
CLI.sdkgen_major_release: A global configuration value identifying
the major version of theSDK
generatorthat was used to generate the currently available SDKs. Theibm-apidocs-cliscript uses this value to determine whichsdkgenversion to use for generating language-specific files. (By
default, the most recent maintenance release for the configured major
release is used.)description: Description of the mapping file. This value is not
used by the CLI.public: An array of JSON objects describing OAS3 API definitions
for public Watson services. These are the OAS3 files in theapis-publicdirectory of thedeveloper-cloud–api-definitionsrepo.private: An array of JSON objects describing OAS3 API definitions
for private (ICP and ICP4D) Watson services. These are the OAS3 files
in theapis-privatedirectory of thedeveloper-cloud–api-definitionsrepo.Within thepublicandprivatearrays, each object maps an API
definition to the default values used byibm-apidocs-cli:service: An identifier for the Watson service described by the
OAS3 file. This identifier is the same as the name of the`cloud-api-docs<https://github.ibm.com/cloud-api-docs>`__ repo
for the service, and is used to clone repos and push generated files
to GHE.openapi: The name of the OAS3 file in theapis-publicorapis-privatedirectory.config: The name of the front-matter configuration file to use
when building the API Reference for the OAS3 file. The specified
configuration file is assumed to exist in thecloud-api-docsrepo
for the service.frontmatter: The name of the directory containing the
front-matter templates to use when building the API Reference for the
OAS3 files. The specified directory must exist in thefrontmatter-generatorrepo.examples: An array listing the names of the JSON files containing
request examples to be merged with the OpenAPI definition at build
time. The listed example files will be copied to the output directory
along with the input OpenAPI file.Python version✅ Tested on Python 3.5, 3.6, and 3.7.ContributingSeeCONTRIBUTING.md.LicenseMIT