Maintenance Operations

The SwaggerHub installation provides a CLI for various maintenance operations. The commands can be run via kubectl exec using the syntax given below.

Usage

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd COMMAND [OPTIONS]

Important

Note the space in -- cmd.

If SwaggerHub is installed in an existing Kubernetes cluster:

  • Run these commands from any machine that has kubectl access to the cluster.

  • Use -n NAMESPACE to specify the namespace where SwaggerHub is installed (typically swaggerhub).

If SwaggerHub is installed on a VM (as an embedded cluster):

  • Run these commands on the VM itself.

  • The namespace is default and can be omitted.

Commands

  • bulk-replace – Find and replace text in all APIs and domains

  • create-admin-user – Create the admin user and a default organization

  • delete-user – Delete a user

  • import-backup – Import a backup from an existing SwaggerHub On-Premise 1.x installation

  • license-usage – View license usage and limits

  • list-apis-domains-templates – List APIs, Domains, Templates (asset), and deleted documents

  • list-custom-templates – List Custom Codegen Templates inctalled

  • list-users – List all users

  • set-default-org – Set the default organization

  • set-logging-level – Set the logging level for SwaggerHub services

  • terms-and-conditions-update-check – Check to see when the Terms and Conditions were last updated

  • test-smtp – Test SMTP settings by sending a test email

  • test-url – Check if SwaggerHub services can reach a specific URL

bulk-replace

Finds and replaces text in all APIs and domains in SwaggerHub. bulk-replace changes all occurrences of the sought-for string in all versions of APIs and domains, including published (read-only) versions.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd bulk-replace SERACH REPLACE

Important

Before running this command, back up your SwaggerHub databases so that you can restore the original content in case of accidental data corruption.

Arguments:

  • SEARCH – The sought-for string (case-sensitive).

  • REPLACE – The replacement string. All occurrences of the SEARCH string will be replaced with this string. Can be an empty string "" to remove any occurrences of the SEARCH string from all definitions.

Note: bulk-replace updates the content in SwaggerHub databases directly, so it does not trigger API-level integrations (such as webhooks) and does not automatically update API mocks. You will need to trigger the integrations on demand to propagate the changes to other systems. Integrations can be triggered manually or in an automated way using SwaggerHub CLI or Registry API.

Example

A common use case is updating the SwaggerHub DNS name in $refs and mock server URLs after SwaggerHub was moved to another DNS name.

kubectl exec -it deploy/swaggerhub-operator -n swaggerhub -- cmd bulk-replace sh.example.com swaggerhub.example.com

Output:

WARNING: If you proceed, all occurrences of "sh.example.com" will be replaced with "swaggerhub.example.com" in ALL definitions stored in SwaggerHub, including published definitions. This will affect 150 definition(s).
This operation cannot be undone. You are strongly advised to take a backup before proceeding.
Are you sure you want to continue? [y/n] y
150/150 definition(s) updated.

Note

The number of definitions refers to the number of versions of APIs and domains.

Output if the sought-for string was not found in any definitions:

No definitions found containing "sh.example.com"

create-admin-user

This command is used during the initial SwaggerHub installation to create the admin user and a default organization.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd create-admin-user USERNAME [-p PASSWORD] EMAIL DEFAULT_ORG

Arguments:

  • USERNAME – Required. The admin username must be between 3 and 20 characters long and can only contain the characters A..Z a..z 0..9 - _ .

  • -p PASSWORD or --password PASSWORD – Optional. The password for the admin user.

    Notes:

    • The password must contain at least seven characters with at least one lowercase letter and one number.

    • If the password contains characters that have a special meaning in Bash (such as ! $ & and others), enclose the password in single quotes or escape the special characters. Example: -p '$passw0rd!'.

    • If the -p argument is omitted, you will be prompted to enter the password when the command is executed.

  • EMAIL – Required. The email address of the admin user. Make sure you have access to this mailbox in case you will need to reset the admin user’s password.

  • DEFAULT_ORG – Required. The name of the organization to create. See the requirements for organization names. The admin user will be the owner of this organization.

delete-user

Delete a user from your SwaggerHub instance to free up a license seat.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd delete-user USERNAME [-p ADMIN_PASSWORD]

Arguments:

  • USERNAME – Required. The user to delete. Case-insensitive. This user is deleted from all organizations, and all APIs and domains owned by this user are also deleted. Deleting the last owner of an organization will result in the organization also being deleted.

  • -p ADMIN_PASSWORD or --password ADMIN-PASSWORD – Optional. The password of the admin user. If omitted, you will be prompted for the password when the command is executed.

    Note: If the password contains characters that have a special meaning in Bash (such as ! $ & and others), enclose the password in single quotes or escape the special characters. Example: -p '$passw0rd!'.

Tip

To bulk delete multiple users, use the User Management API.

license-usage

View your license information: the expiration date, the maximum number of users, and the number of existing registered users.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd license-usage

Sample output:

Your license will expire on: 12/31/2022

Using 5 out of 50 designers.

Using 10 out of 100 users.

Sample output if the license has expired and the maximum number of users has been reached:

Your license expired on: 10/30/2021

Using 50 out of 50 designers.
  WARNING: You will not be able to assign any more designer roles as the licensed limit has been reached.

Using 100 out of 100 users.
  WARNING: Users will not be able to sign up as the licensed limit has been reached.

Note

You can also view your license information on the License tab in the Admin Console.

list-apis-domains-templates

List APIs, Domains, Templates (asset) and deleted documents. It can be run with no flag to list all of the data or use one or more options.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd list-apis-domains-templates

Options:

  -o, --owner <owner>    Owner that the API belongs to
  -n, --name <name>      API name
  -t, --type <type>      API type (choices: API, DOMAIN, TEMPLATE
  -f, --format <format>  Output format (json/yaml)
  -s, --save             Save output to file
  -h, --help             display help for command

Sample output:

[
  {
    "apiId": "api0",
    "type": "API",
    "versionId": "1.0.0",
    "createdBy": "admin",
    "owner": "SmartBear"
  }
]

Sample output if more options are applied:

- apiId: api0
  type: API
  versionId: 1.0.0
  createdBy: admin
  owner: SmartBear

list-custom-templates

List Custom Codegen Templates installed. See Codegen Templates.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd list-custom-templates

Sample output:

List of custom templates:
custom_codegen_1-swagger-codegen-1.0.0.jar
custom_codegen_2-swagger-codegen-1.0.0.jar
custom_codegen_1-swagger-codegen-1.0.0.jar
custom_codegen_2-swagger-codegen-1.0.0.jar

list-users

List all SwaggerHub users and their email addresses.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd list-users

Sample output:

Username                                 E-mail address                           License type                             Designer in [Org]
===============================================================================================================================================================================
admin                                    [email protected]                        Designer                                 SmartBear,Organization2,Organization3,Organization4
coll1                                    [email protected]                          User
[email protected]                          [email protected]                          -
[email protected]                          [email protected]                          -
user1                                    [email protected]                          Designer                                 Organization2,SmartBear
user2                                    [email protected]                          User
user3                                    [email protected]                          Designer                                 Organization4,Organization2,Organization3
user4                                    [email protected]                          Designer                                 Organization4
[email protected]                          [email protected]                          -
[email protected]                          [email protected]                          -
===============================================================================================================================================================================
Description:


Assigned role
No role assigned
'-' assigned role, inactive account (will activate once the user accepts invitation) therefore doesn't take up a license seat
'-' no assigned role, inactive account (will activate once the user accepts invitation) therefore doesn't take up a license seat
Designer in - a list of organizations, where the user has Designer license typeUsername                                E-mail address
======================================================================
admin                                   [email protected]
alice                                   [email protected]
bob                                     [email protected]

Tip

You can also use the User Management API to get the user list.

import-backup

Imports a backup created in SwaggerHub 1.20.1–1.29.x. This command is used to migrate data from an existing 1.x installation to SwaggerHub On-Premise 2.x.Migrating from SwaggerHub On-Premise 1.x to 2.7

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd import-backup /path/to/backup.tar.gz

The backup file (.tar.gz) must have been previously copied to the swaggerhub-operator container within the SwaggerHub deployment. The backup file path specified in the command must be local to the swaggerhub-operator container.

For more information about using import-backup, see Migrating Data From SwaggerHub 1.x to 2.x.Migrating from SwaggerHub On-Premise 1.x to 2.7

set-default-org

Set the default organization.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd set-default-org ORG_NAME [-p ADMIN_PASSWORD]

Arguments:

  • ORG_NAME – The name of the organization you want to make default. Case-insensitive. This organization must already exist in SwaggerHub, otherwise the command fails with an error. The admin user will be automatically added as an owner to this organization (if not already an owner).

    If the specified organization is already default, the command completes successfully, but has no effect.

  • -p ADMIN_PASSWORD or --password ADMIN-PASSWORD – Optional. The password of the admin user. If omitted, you will be prompted for the password when the command is executed.

    Note: If the password contains characters that have a special meaning in Bash (such as ! $ & and others), enclose the password in single quotes or escape the special characters. Example: -p '$passw0rd!'.

set-logging-level

Set the logging level for one or all of SwaggerHub services. Debug-level logging can be useful for troubleshooting.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd set-logging-level LEVEL [SERVICE]

Arguments:

  • LEVEL – Required. Possible values: default and debug (more detailed).

  • SERVICE – Optional. A service for which the logging level will be changed. If omitted, the logging level is changed for all available services. The available service names are:

    • products-api-service

    • swaggerhub-backend

    • swaggerhub-frontend

    • swaggerhub-registry-apis

When successful, this command has no output.

terms-and-conditions-update-check

Returns the date when the Terms and Conditions were last updated.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd terms-and-conditions-update-check

test-smtp

SwaggerHub requires an SMTP server to send email notifications. You can use this command to test the connection from SwaggerHub to your SMTP server and send a test email message.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd test-smtp -e EMAIL_ADDRESS -h HOST -p PORT -r PROTOCOL -u USERNAME - w PASSWORD

All arguments are optional and if omitted will use the values specified in the SMPT settings for SwaggerHub.

  • -e, --email EMAIL_ADDRESS – The email address to send a test message to. For example, [email protected]. If omitted, defaults to the Email Address specified in the SwaggerHub SMTP settings.

  • -h, --host HOST – The SMTP server hostname or IP address. For example, smtp.gmail.com.

  • -p, --port PORT – The SMTP server port. The typical port numbers are 465 for SSL, 587 for STARTTLS, and 25 for unencrypted (plain) connections.

  • -r, --protocol PROTOCOL – The connection type: PLAIN, SSL, or TLS (STARTTLS).

  • -u, --username USERNAME – The username for the SMTP server.

  • -w, --password PASSWORD – The password for the SMTP server.

    Note: If the password contains characters that have a special meaning in Bash (such as ! $ & and others), enclose the password in single quotes or escape the special characters. Example: -w '$passw0rd!'.

Examples

Test SwaggerHub’s current SMTP settings:

kubectl exec -it deploy/swaggerhub-operator -- cmd test-smtp

Send a test email to a recipient through the SMTP server specified in the SwaggerHub settings:

kubectl exec -it deploy/swaggerhub-operator -- cmd test-smtp -e [email protected]

Send a test email to a recipient through a specific SMTP server:

kubectl exec -it deploy/swaggerhub-operator -- cmd test-smtp -e [email protected] -h smtp.example.com -p 465 -r SSL -u user -w password

Sample output if SwaggerHub could not connect to the SMTP server:

Error during sending email: {"code":"EAUTH","response":"535 Authentication Credentials Invalid","responseCode":535,"command":"AUTH PLAIN"}

test-url

Checks if the SwaggerHub services can reach a specific URL. You can use this command to test outbound connectivity through the proxy server configured for SwaggerHub.

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd test-url URL [--proxy PROXY_SERVER]

Arguments:

  • URL – Required. A URL to test, for example, https://swagger.io. Make sure to include http:// or https:// at the beginning of the URL. If the URL’s domain is in the Bypass Proxy For list, the command will connect to the URL directly without a proxy.

  • --proxy PROXY_SERVER – Optional. An HTTP(S) proxy to use. If omitted, the proxy specified in the SwaggerHub settings will be used instead. The value must be in the format:

    http://[user:password@]host[:port]

    Important

    The http:// prefix is mandatory.

    Examples:

    http://10.40.0.4:8888
http://user:[email protected]:8888

test-url sends an HTTP GET request to the specified URL and waits for a response from the server for 10 seconds. The test is considered successful if the connection was established and a response was received (regardless of the HTTP status code). SSL certificates from the SSL Certificate Trust Chain are trusted in addition to system defaults. HTTP redirects are followed automatically.

Sample output if the URL is reachable:

URL is reachable (using HTTP proxy server). Status code: 200

Sample output in case of an error:

URL is not reachable. Error: DNS lookup failed

See Also

In this section:
© 2024
Publication date: