Client documentation

Client docs

Requirements

• Go > 1.18

Requirements

1. OpenAPI generator: https://openapi-generator.tech/docs/installation#bash-launcher-script

The specific version used can be found in client/.openapi-generator/VERSION

Install it globally (required by generate.sh):

npm install -g @openapitools/openapi-generator-cli

2. openapi format: https://github.com/thim81/openapi-format

Install it globally (required by generate.sh):

npm install -g openapi-format

Generating the client:

./generate.sh automatically picks the OpenAPI source:

1. It first tries http://localhost:4242/docs/openapi.json
2. If local Unleash is not reachable, it falls back to https://us.app.unleash-hosted.com/ushosted/docs/openapi.json

This lets you generate the client against a specific local server version (for example a pinned enterprise image). During generation, servers is normalized to a deterministic placeholder (https://unleash.example.com) to avoid source-specific URL diffs in generated docs (local vs hosted).

You can override this placeholder if needed:

OPENAPI_SERVER_URL=https://my-unleash.example ./generate.sh

Running Unleash with Docker Compose

The docker-compose.yml defaults to OSS Unleash:

docker compose up

To start the enterprise image, set UNLEASH_DOCKER_IMAGE (same pattern used in terraform-provider-unleash):

UNLEASH_DOCKER_IMAGE=unleashorg/unleash-enterprise:latest docker compose up

To pin a specific enterprise version (for example 7.4.1):

UNLEASH_DOCKER_IMAGE=unleashorg/unleash-enterprise:7.4.1 docker compose up

With that running, ./generate.sh will use http://localhost:4242/docs/openapi.json from that exact image.

Enterprise features also require a valid license key, passed as UNLEASH_DEV_LICENSE:

UNLEASH_DEV_LICENSE=<your license key> \
UNLEASH_DOCKER_IMAGE=unleashorg/unleash-enterprise:latest \
docker compose up

Generate client from openapi.json

./generate.sh

After generating the code you can use main.go to test it works (before running the command below start Unleash server with docker compose up)

go run main.go -unleash-api http://localhost:4242 -authorization *:*.unleash-insecure-admin-api-token

Testing

Testing relies on a running environment. You can use docker-compose.yml file to spin up an environment with a clean state and predictable admin API token.

Note: some tests rely on an enterprise version of Unleash. To run those tests locally you need to set UNLEASH_ENTERPRISE=true, and start Docker with UNLEASH_DOCKER_IMAGE=unleashorg/unleash-enterprise:latest. You also need a valid license key provided as UNLEASH_DEV_LICENSE=<your license key>.

A basic test is automatically generated by the tool (find them under client/test), but they don't have a default configuration and doesn't have payloads required for some of the endpoints. This is the reason why the tools marks all of them as Skip. Still they're a good starting point.

We recommend copying specific tests from client/test into test and adapting them accordingly. We've done that already for api_users_test and some of its methods. Also, recommended to use apiClient := testClient() to instantiate the client.

Running the tests

1. (optional but recommended) docker compose rm --force
2. docker compose up
3. go test ./test/... -count=1 -v
4. UNLEASH_ENTERPRISE=true go test ./test/... -count=1 -v

Validating external PRs (maintainers)

PRs from forks do not get access to repository secrets in GitHub Actions (for example UNLEASH_DEV_LICENSE), so enterprise matrix jobs may fail in the fork context.

To validate the same changes with secrets enabled:

1. Fetch the PR head into a local branch:

git fetch origin pull/<PR_NUMBER>/head:pr-<PR_NUMBER>

2. Push that branch to this repository:

git push origin pr-<PR_NUMBER>

3. Run the workflow on pr-<PR_NUMBER> from the base repository Actions page.

4. (optional) Delete the temporary branch when done:

git push origin --delete pr-<PR_NUMBER>