This repository has been archived by the owner on Aug 11, 2022. It is now read-only.
1. How to get started
Getting started with the API-Manager Promote CLI is very simple.
- an API-Manager Version 7.X up & running
- the project has been tested with version 7.6.2 SP2, 7.6.2 SP3, 7.6.2 SP4 & 7.7 (you can verify compatibility yourself as described here)
- Either an environment to execute a very simple Shell-Script or BAT-File, which wraps a Java-Program
- or executing a binary when installed with Chocolately.org
- an installed Java Runtime Environment 8 or higher and JAVA_HOME configured
- the machine must have access to the API-Manager REST-API on Default-Port: 8075
- Download the latest release from here
- best is to extract the archive including the folder: (e.g. swagger-promote-1.6.2) somewhere on your disk
"C:\Axway\Tools" - now create a Short-Cut-Folder pointing to the extracted version like so:
"C:\Axway\Tools\swagger-promote" --> "C:\Axway\Tools\swagger-promote-1.6.2" - Add the following to you PATH:
"C:\Axway\Tools\swagger-promote\scripts" - You can run now Swagger-Promote with one of the following scripts:
api-import.bat, api-export.bat, api-import.sh, api-export.sh - With that structure:
you can just extract every new version into the same folder and just update the short-cut to the version you want
- best is to extract the archive including the folder: (e.g. swagger-promote-1.6.2) somewhere on your disk
If you want to use Swagger-Promote on Windows and you are already using Chocolately.org the installation is just that simple:
choco install axway-swagger-promote
To upgrade to the newest version just say:
choco upgrade axway-swagger-promote
After installation you can just run api-import or api-export
- get it from Maven-Central to reference it as a dependency in your projects
<dependency>
<artifactId>axway-swagger-promote-core</artifactId>
<groupId>com.github.axway-api-management-plus.swagger-promote</groupId>
<version>1.6.2</version>
</dependency>This is especially interesting when integrated into a pipeline based on Maven.
Use one of the scripts: scripts/api-import.sh or scripts/api-import.bat to see the complete usage. Obviously Swagger-Promote is supposed to run as part of CI/CD-Pipeline. Learn more here how to integrate it into your pipeline to improve the API-Developer experience.
------------------------------------------------------------------------
API-Manager Promote: 1.6.2 - I M P O R T
To report issues or get help, please visit:
https://github.com/Axway-API-Management-Plus/apimanager-swagger-promote
------------------------------------------------------------------------
usage: API-Import [-a <swagger_file.json>] -c <api_config.json> [-clientAppsMode <ignore|replace|add>] [-clientOrgsMode
<ignore|replace|add>] [-detailsExportFile <APIDetails.properties>] [-f <true/[false]>] [-h <api-host>] [-iq <true/[false]>] [-p
<changeme>] [-port <8181>] [-quotaMode <ignore|replace|add>] [-rc] [-s <preprod>] [-u <apiadmin>]
-a,--apidefinition <swagger_file.json> (Optional) The API Definition either as Swagger (JSON-Formated) or a WSDL for SOAP-Services:
- in local filesystem using a relative or absolute path. Example: swagger_file.json
Please note: Local filesystem is not supported for WSDLs. Please use direct URL or a
URL-Reference-File.
- a URL providing the Swagger-File or WSDL-File. Examples:
[username/password@]https://any.host.com/my/path/to/swagger.json
[username/password@]http://www.dneonline.com/calculator.asmx?wsdl
- a reference file called anyname-i-want.url which contains a line with the URL
(same format as above for Swagger or WSDL). If not specified, the API Definition
configuration is read directly from the JSON-Formatted API-Config
-c,--contract <api_config.json> This is the JSON-Formatted API-Config containing information how to expose the API
-clientAppsMode <ignore|replace|add> Controls how configured Client-Applications are treated. Defaults to add!
-clientOrgsMode <ignore|replace|add> Controls how configured Client-Organizations are treated. Defaults to add!
-detailsExportFile <APIDetails.properties> Configure a filename, to get a Key=Value file containing information about the created API.
-f,--force <true/[false]> Breaking changes can't be imported without this flag, unless the API is unpublished.
-h,--host <api-host> The API-Manager hostname the API should be imported
-iq,--ignoreQuotas <true/[false]> Use this flag to ignore configured API quotas.
-p,--password <changeme> Password used to authenticate
-port <8181> Optional parameter to declare the API-Manager port. Defaults to 8075.
-quotaMode <ignore|replace|add> Controls how quotas are managed in API-Manager. Defaults to add!
-rc,--returncodes Print the possible return codes and description.
-s,--stage <preprod> The stage this API should be imported.
Will be used to lookup stage specific API-Config overrides (e.g.: api_config.preprod.json)
-u,--username <apiadmin> Username used to authenticate. Please note, that this user must have Admin-Role
ERROR: Missing required option: c
You may run one of the following examples:
api-import -c samples/basic/minimal-config.json -a ../petstore.json -h localhost -u apiadmin -p changeme
api-import -c samples/basic/minimal-config.json -a ../petstore.json -h localhost -u apiadmin -p changeme -s prod
api-import -c samples/complex/complete-config.json -a ../petstore.json -h localhost -u apiadmin -p changeme
Using parameters provided in properties file stored in conf-folder:
api-import -c samples/basic/minimal-config-api-definition.json -s api-env
For more information and advanced examples please visit:
https://github.com/Axway-API-Management-Plus/apimanager-swagger-promote/tree/develop/modules/swagger-promote-core/src/main/assembly/samples
https://github.com/Axway-API-Management-Plus/apimanager-swagger-promote/wiki
Swagger-Promote also supports to export the actual state of an API from a running API-Manager. This is useful if you have managed APIs manually in the past and would like to use Swagger-Promote in the future. By exporting the APIs, which is also possible in bulk mode, you can export the actual state all of your APIs, just by using one of the scripts: scripts/api-export.sh or scripts/api-export.bat to see the complete usage
------------------------------------------------------------------------
API-Manager Promote: 1.6.4 - E X P O R T
To report issues or get help, please visit:
https://github.com/Axway-API-Management-Plus/apimanager-swagger-promote
------------------------------------------------------------------------
usage: API-Export -a </api/v1/my/great/api> [-h <api-host>] [-l <my/apis>] [-p <changeme>] [-port <8181>] [-s <preprod>] [-u <apiadmin>] [-v
<vhost.customer.com>]
-a,--api-path </api/v1/my/great/api> Define the APIs to be exported, based on the exposure path.
You can use wildcards to export multiple APIs:
-a /api/v1/my/great/api : Export a specific API
-a * : Export all APIs
-a /api/v1/any* : Export all APIs with this prefix
-a */some/other/api : Export APIs end with the same path
-df,--deleteFolder <true> Controls if an existing local folder should be deleted. Defaults to false.
-h,--host <api-host> The API-Manager hostname from where to export
-l,--localFolder <my/apis> Defines the location to store API-Definitions locally. Defaults to current folder.
For each API a new folder is created automatically.
-p,--password <changeme> Password used to authenticate
-port <8181> Optional parameter to declare the API-Manager port. Defaults to 8075.
-s,--stage <preprod> The Stage or basically the API-Manager environment you want use.
Provide an env.<stage>.properties with required parameters like host, username, password.
-u,--username <apiadmin> Username used to authenticate. Please note, that this user must have Admin-Role
-v,--vhost <vhost.customer.com> Limit the export to that specific host.
ERROR: Missing required option: a
You may run one of the following examples:
api-export -a /api/v1/ -l my_apis -h location -u apiadmin -p changeme
api-export -a "/api/v1/*" -l my_apis -h location -u apiadmin -p changeme
Using parameters provided in properties file stored in conf-folder:
api-export -a /api/v1/ -l my_apis -s api-env
api-export -a "*" -l all_my_apis -s api-env
For more information visit: https://github.com/Axway-API-Management-Plus/apimanager-swagger-promote/wiki
With that export, you get:
- the API-Configuration-File
- the image if used
- all certificates
- the configured Quotas (System- and Application default)
- list of granted organizations
- list of subscribed applications
The core concept is to fully control the API configuration, such as security, the image, certificates, policies, etc. with the provided API-Config in JSON. Learn more about this here.
Please note, almost all parameters given in the API-Configuration file can be externalized into an environment specific property files. Obviously when exporting APIs all parameters are written directly into the API-Config-File. If you would like to declare parameters are See here