Skip to content

Doc: Improve Documentation #179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lbroudoux merged 1 commit into from
Sep 8, 2025
Merged

Doc: Improve Documentation #179

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 41 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,130 +17,59 @@ Current development version is `0.5.6`. [![GitHub Workflow Status](https://img.s

It is available as a container image named `quay.io/microcks/microcks-cli:nightly`.

## Usage instructions
## CLI Command Overview

Usage is simply `microcks-cli [command]`

where `[command]` can be one of the following:

* `version` to check this CLI version,
* `help` to display usage informations,
* `test` to launch new test on Microcks server.
* `import` to import API artifacts on Microcks server.

### Test command

The `test` command has a bunch of arguments and flags so that you can use it that way:

```
microcks-cli test <apiName:apiVersion> <testEndpoint> <runner>
--microcksURL=<> --waitFor=5sec
--keycloakClientId=<> --keycloakClientSecret=<>
```

The arguments:

* `<apiName:apiVersion>` : Service to test reference. Example: `'Beer Catalog API:0.9'`
* `<testEndpoint>` : URL where is deployed implementation to test
* `<runner>` : Test strategy (one of: `HTTP`, `SOAP`, `SOAP_UI`, `POSTMAN`, `OPEN_API_SCHEMA`, `ASYNC_API_SCHEMA`, `GRPC_PROTOBUF`, `GRAPHQL_SCHEMA`)

The flags:

* `--microcksURL` for the Microcks API endpoint,
* `--waitFor` for the time to wait for test to finish (int + one of: milli, sec, min),
* `--keycloakClientId` for the Keycloak Realm Service Account ClientId,
* `--keycloakClientSecret` for the Keycloak Realm Service Account ClientSecret.

> Since `0.5.2` release, `microcks-cli` also works in unauthenticated mode, without Keycloak being deployed and configured with your Microcks instance. However, you still have to specify the Keycloak flags on the command even if you put random values there. For eg. `--keycloakClientId=foo --keycloakClientSecret=bar`.

Real life example command and execution:

```sh
$ ./microcks-cli test 'Beer Catalog API:0.9' http://localhost:9090/api/ POSTMAN \
--microcksURL=http://localhost:8080/api/ \
--keycloakClientId=microcks-serviceaccount \
--keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 \
--waitFor=3sec
[...]
MicrocksClient got status for test "5c1781cf6310d94f8169384e" - success: false, inProgress: true
MicrocksTester waiting for 2 seconds before checking again.
MicrocksClient got status for test "5c1781cf6310d94f8169384e" - success: true, inProgress: false
Full TestResult details are available here: http://localhost:8080/#/tests/5c1781cf6310d94f8169384e
### Usage
```bash
microcks [command] [flags]
```

#### Advanced options

The `test` command provides additional flags for advanced usages and options:

* `--verbose` allows to dump on standard output all the HTTP requests and responses,
* `--insecure` allows to interact with Microcks and Keycloak instances through HTTPS without checking certificates issuer CA,
* `--caCerts=<path1,path2>` allows to specify additional certificates CRT files to add to trusted roots ones,
* `--secretName='<Secret Name>'` is an optional flag specifying the name of a Secret to use for connecting endpoint,
* `--filteredOperations=<JSON>` allows to filter a list of operations to launch a test for,
* `--operationsHeaders=<JSON>` allows to override some operations headers for the tests to launch,
* `--oAuth2Context=<JSON>` allows specification of an OAuth2 grant flow to execute before launching the test (starts with Microcks version `1.8.0`).
### Availabel Commands
| Command | Description | Documentation |
| ------------ | -------------------------------------------------------- | ----------------------------------------------- |
| `login` | Log in to a Microcks instance using Keycloak credentials | [`login`](documentation/cmd/login.md) |
| `logout` | Log out and remove authentication from a given context | [`logout`](documentation/cmd/logout.md) |
| `context` | Manage CLI contexts (list, use, delete) | [`context`](documentation/cmd/context.md) |
| `start` | Start a local Microcks instance via Docker/Podman | [`start`](documentation/cmd/start.md) |
| `stop` | Stop a local Microcks instance | [`stop`](documentation/cmd/stop.md) |
| `import` | Import API spec files from local filesystem | [`import`](documentation/cmd/import.md) |
| `import-url` | Import API spec files directly from a remote URL | [`import-url`](documentation/cmd/import-url.md) |
| `test` | Run tests against a deployed API using selected runner | [`test`](documentation/cmd/test.md) |
| `version` | Print Microcks CLI version | [`version`](documentation/cmd/version.md) |

### Options

| Flag | Description |
| ------------------------ | ------------------------------------------- |
| `-h, --help` | help for microck command |
| `--config` | Path to Microcks config file |
| `--microcks-context` | Name of the Microcks context to use |
| `--verbose` | Produce dumps of HTTP exchanges |
| `--insecure-tls` | Allow insecure HTTPS connections |
| `--caCerts` | Comma-separated paths of CA cert files |
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
| `--microcksURL` | Microcks API URL |

Overriden test operations headers is a JSON strings where 1st level keys are operation name (eg. `GET /beer`) or `globals` for header applying to all the operations of the API. Headers are specified as an array of objects defining `key` and `values` properties.

Here's below an example of using some of this flags:

```sh
$ ./microcks-cli test 'Beer Catalog API:0.9' http://localhost:9090/api/ OPEN_API_SCHEMA \
--microcksURL=http://localhost:8080/api/ \
--keycloakClientId=microcks-serviceaccount \
--keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 \
--insecure --verbose --waitFor=3sec \
--filteredOperations='["GET /beer", "GET /beer/{name}"]' \
--operationsHeaders='{"globals": [{"name": "x-api-key", "values": "my-values"}], "GET /beer": [{"name": "x-trace-id", "values": "xcvbnsdfghjklm"}]}' \
--oAuth2Context='{"clientId": "microcks-test", "clientSecret": "ab54d329-e435-41ae-a900-ec6b3fe15c54", "tokenUri": "https://idp.acme.org/realms/my-app/protocol/openid-connect/token", "grantType": "CLIENT_CREDENTIALS"}'
## Installation

MicrocksClient got status for test "64c25f7ddec62569f9a0ed95" - success: true, inProgress: false
Full TestResult details are available here: http://localhost:8080/#/tests/64c25f7ddec62569f9a0ed95
### Building from Source
To build the CLI locally:
```bash
make build-local
```

### Import command

The `import` command has one argument and common flags with `test` command. You can use it that way:

The resulting binary will be available at:
```bash
/build/dist/microcks
```
microcks-cli import <specificationFile1[:primary],specificationFile2[:primary]>
--microcksURL=<>
--keycloakClientId=<> --keycloakClientSecret=<>
```

The arguments:

* `<specificationFile1[:primary],specificationFile2[:primary]>` : Comma separated list of API specs to import with flag telling if it's a primary artifact. Example: `'specs/my-openapi.yaml:true,specs/my-postmancollection.json:false'`

The flags:

* `--microcksURL` for the Microcks API endpoint,
* `--keycloakClientId` for the Keycloak Realm Service Account ClientId,
* `--keycloakClientSecret` for the Keycloak Realm Service Account ClientSecret.

> Since `0.5.2` release, `microcks-cli` also works in unauthenticated mode, without Keycloak being deployed and configured with your Microcks instance. However, you still have to specify the Keycloak flags on the command even if you put random values there. For eg. `--keycloakClientId=foo --keycloakClientSecret=bar`.

Real life example command and execution:

```sh
$ ./microcks-cli import 'samples/weather-forecast-openapi.yml:true,samples/weather-forecast-postman.json:false' \
--microcksURL=http://localhost:8080/api/ \
--keycloakClientId=microcks-serviceaccount \
--keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1
Microcks has discovered 'WeatherForecast API:1.1.0'
Microcks has discovered 'WeatherForecast API:1.1.0'
You can move it to a location in your $PATH for global usage, for example:
```bash
sudo mv build/dist/microcks /usr/local/bin/microcks
```

#### Advanced options

The `import` command provides additional flags for advanced usages and options:

* `--verbose` allows to dump on standard output all the HTTP requests and responses,
* `--insecure` allows to interact with Microcks and Keycloak instances through HTTPS without checking certificates issuer CA,
* `--caCerts=<path1,path2>` allows to specify additional certificates CRT files to add to trusted roots ones,


## Installation

### Binary

Expand Down
39 changes: 39 additions & 0 deletions documentation/cmd/context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
## `microcks context` – Manage CLI Contexts
Switch between, list, or delete configured Microcks CLI contexts.

### Usage
```bash
microcks context [CONTEXT] [flags]
```

### Examples
```bash
# List all available contexts
microcks context/ctx

# Switch to this context
microcks context/ctx http://localhost:8080

# Delete the context
microcks context/ctx http://localhost:8080 --delete/-d
```
### Options
| Flag | Description |
| -------------- | ---------------------------- |
| `-d, --delete` | Delete the specified context |
| `-h, --help` | help for context |

### Options Inherited from Parent Commands
| Flag | Description |
| ------------------------ | ------------------------------------------- |
| `--config` | Path to Microcks config file |
| `--microcks-context` | Name of the Microcks context to use |
| `--verbose` | Produce dumps of HTTP exchanges |
| `--insecure-tls` | Allow insecure HTTPS connections |
| `--caCerts` | Comma-separated paths of CA cert files |
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
| `--microcksURL` | Microcks API URL |



85 changes: 36 additions & 49 deletions documentation/cmd/import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,43 @@
# Import Command
## `microcks import` – Import API Artifacts into Microcks
Uploads one or more API spec files (e.g., OpenAPI, AsyncAPI, Postman) to the Microcks server and optionally watches them for changes.

The `import` command in Microcks CLI is used to upload and register API specification artifacts (like OpenAPI, AsyncAPI, Postman collections, etc.) into a Microcks server.
### Usage
```bash
microcks import <specFile1[:main]>,<specFile2[:main]> [flags]
```

### Examples
```bash
# Import a single artifact (marked as main)
microcks import ./api.yaml

📝 Description
# Specify mainArtifact flag for each file
microcks import ./api.yaml:false,./schema.json:true

The `import` command enables developers to push one or multiple API artifacts to a Microcks instance. It supports secure authentication via Keycloak and allows custom TLS configurations for secure communication.
# Import and watch file for changes
microcks import ./api.yaml --watch

📌 Usage
```bash
microcks import <specificationFile1[:primary]>,<specificationFile2[:primary]> \
--microcksURL <microcks-api-url> \
--keycloakClientId <client-id> \
--keycloakClientSecret <client-secret> \
[--insecure] \
[--caCerts <cert-paths>] \
[--verbose]
# Import specification to microcks without logining to microcks
microck import ./api.yaml \
--micrcoksURL <microcks-url> \
--keycloakClientId <client-id> \
--keycloakClientSecret <client-secret>
```
Arguments
- `<specificationFile[:primary]>`:
A comma-separated list of specification file paths to import.
Optionally, each file can be suffixed with `:true` or `:false` to indicate whether it's the primary artifact.

| Flag | Type | Required | Description |
|-------------------------|---------|----------|-----------------------------------------------------------------------------|
| `--microcksURL` | string | ✅ | The URL of the Microcks API endpoint. |
| `--keycloakClientId` | string | ✅ | The Keycloak Service Account Client ID for OAuth2 authentication. |
| `--keycloakClientSecret`| string | ✅ | The Keycloak Service Account Client Secret for authentication. |
| `--insecure` | bool | ❌ | Allow insecure TLS connections (e.g., self-signed certs). |
| `--caCerts` | string | ❌ | Comma-separated paths to additional CA certificate files (PEM format). |
| `--verbose` | bool | ❌ | Enable verbose mode to dump HTTP requests and responses to the console. |
### Options
| Flag | Description |
| ----------- | --------------------------------------------------- |
| `-h, --help`| help for import |
| `--watch` | Watch the file(s) and auto-reimport them on changes |

🧪 Examples
- Basic Import
```bash
microcks import my-api.yaml \
--microcksURL http://localhost:8080/api \
--keycloakClientId my-client \
--keycloakClientSecret my-secret
```
- Import Multiple Files with Primary Indicator
```bash
microcks import openapi.yaml:true,postman.json:false \
--microcksURL https://microcks.example.com/api \
--keycloakClientId my-client \
--keycloakClientSecret my-secret
```
- Using Custom TLS CA Certificates and Verbose Logging
```bash
microcks-cli import spec.yaml \
--microcksURL https://microcks.example.com/api \
--keycloakClientId my-client \
--keycloakClientSecret my-secret \
--caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \
--verbose
```
### Options Inherited from Parent Commands
| Flag | Description |
| ------------------------ | ------------------------------------------- |
| `--config` | Path to Microcks config file |
| `--microcks-context` | Name of the Microcks context to use |
| `--verbose` | Produce dumps of HTTP exchanges |
| `--insecure-tls` | Allow insecure HTTPS connections |
| `--caCerts` | Comma-separated paths of CA cert files |
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
| `--microcksURL` | Microcks API URL |
78 changes: 26 additions & 52 deletions documentation/cmd/importURL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,60 +1,34 @@
# ImportURL Command
## `microcks import-url` – Import API Artifacts from URL
Imports API specification files (OpenAPI, AsyncAPI, etc.) hosted at a remote URL into the Microcks server.

The `import-url` command in Microcks CLI is used to upload and register API specification artifacts(like OpenAPI, AsyncAPI, Postman collections, etc.) from URLs into a Microcks server.

📝 Description

The `import-url` command provides a convenient way to register API specifications (OpenAPI, AsyncAPI, Postman collections, etc.) hosted online without needing to download them manually. This is useful for CI/CD pipelines or importing frequently updated remote specs.

📌 Usage
### Usage
```bash
microcks import-url <url1[:primary]>,<url2[:primary]> \
--microcksURL <microcks-api-url> \
--keycloakClientId <client-id> \
--keycloakClientSecret <client-secret> \
[--insecure] \
[--caCerts <cert-paths>] \
[--verbose]
microcks import-url <specURL1[:main][:secret]>,<specURL2[:main][:secret]> [flags]
```

Arguments
- `<url[:primary]>`:
A comma-separated list of publicly accessible URLs pointing to specification files.
Optionally, each URL can be suffixed with `:true` or `:false` to mark it as a primary artifact.


| Flag | Type | Required | Description |
|-------------------------|---------|----------|-----------------------------------------------------------------------------|
| `--microcksURL` | string | ✅ | The URL of the Microcks API endpoint. |
| `--keycloakClientId` | string | ✅ | The Keycloak Service Account Client ID for OAuth2 authentication. |
| `--keycloakClientSecret`| string | ✅ | The Keycloak Service Account Client Secret for authentication. |
| `--insecure` | bool | ❌ | Allow insecure TLS connections (e.g., self-signed certs). |
| `--caCerts` | string | ❌ | Comma-separated paths to additional CA certificate files (PEM format). |
| `--verbose` | bool | ❌ | Enable verbose mode to dump HTTP requests and responses to the console. |

🧪 Examples
- Importing from a Single URL
### Example
```bash
microcks import-url https://example.com/api/openapi.yaml \
--microcksURL http://localhost:8080/api \
--keycloakClientId my-client \
--keycloakClientSecret my-secret
```
# Import a single artifact (marked as main)
microcks import-url https://example.com/openapi.yaml

- Importing Multiple Remote Artifacts with Primary Designation
```bash
microcks import-url https://example.com/openapi.yaml:true,https://example.com/postman.json:false \
--microcksURL https://microcks.example.com/api \
--keycloakClientId my-client \
--keycloakClientSecret my-secret
```
# Specify mainArtifact flag for each file
microcks import-url https://example.com/spec1.yaml:true,https://example.com/spec2.yaml:false

- Using Custom TLS CA Certificates and Verbose Logging
```bash
microcks import-url https://mydomain.com/api/spec.yaml \
--microcksURL https://microcks.example.com/api \
--keycloakClientId my-client \
--keycloakClientSecret my-secret \
--caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \
--verbose
# Import specification to microcks without logining to microcks
microck import-url https://example.com/openapi.yaml \
--micrcoksURL <microcks-url> \
--keycloakClientId <client-id> \
--keycloakClientSecret <client-secret>
```

### Options Inherited from Parent Commands
| Flag | Description |
| ------------------------ | ------------------------------------------- |
| `--config` | Path to Microcks config file |
| `--microcks-context` | Name of the Microcks context to use |
| `--verbose` | Produce dumps of HTTP exchanges |
| `--insecure-tls` | Allow insecure HTTPS connections |
| `--caCerts` | Comma-separated paths of CA cert files |
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
| `--microcksURL` | Microcks API URL |
Loading