Skip to content

Commit 6d1257b

Browse files
Harsh4902Harsh4902
authored
Improved documentation and README.md to reflect recent improvemnts/chagnes in cli (#179)
Signed-off-by: Harsh4902 <[email protected]>
1 parent cfb301c commit 6d1257b

File tree

10 files changed

+334
-237
lines changed

10 files changed

+334
-237
lines changed

‎README.md‎

Lines changed: 41 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -17,130 +17,59 @@ Current development version is `0.5.6`. [![GitHub Workflow Status](https://img.s
1717

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

20-
## Usage instructions
20+
## CLI Command Overview
2121

22-
Usage is simply `microcks-cli [command]`
23-
24-
where `[command]` can be one of the following:
25-
26-
* `version` to check this CLI version,
27-
* `help` to display usage informations,
28-
* `test` to launch new test on Microcks server.
29-
* `import` to import API artifacts on Microcks server.
30-
31-
### Test command
32-
33-
The `test` command has a bunch of arguments and flags so that you can use it that way:
34-
35-
```
36-
microcks-cli test <apiName:apiVersion> <testEndpoint> <runner>
37-
--microcksURL=<> --waitFor=5sec
38-
--keycloakClientId=<> --keycloakClientSecret=<>
39-
```
40-
41-
The arguments:
42-
43-
* `<apiName:apiVersion>` : Service to test reference. Example: `'Beer Catalog API:0.9'`
44-
* `<testEndpoint>` : URL where is deployed implementation to test
45-
* `<runner>` : Test strategy (one of: `HTTP`, `SOAP`, `SOAP_UI`, `POSTMAN`, `OPEN_API_SCHEMA`, `ASYNC_API_SCHEMA`, `GRPC_PROTOBUF`, `GRAPHQL_SCHEMA`)
46-
47-
The flags:
48-
49-
* `--microcksURL` for the Microcks API endpoint,
50-
* `--waitFor` for the time to wait for test to finish (int + one of: milli, sec, min),
51-
* `--keycloakClientId` for the Keycloak Realm Service Account ClientId,
52-
* `--keycloakClientSecret` for the Keycloak Realm Service Account ClientSecret.
53-
54-
> 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`.
55-
56-
Real life example command and execution:
57-
58-
```sh
59-
$ ./microcks-cli test 'Beer Catalog API:0.9' http://localhost:9090/api/ POSTMAN \
60-
--microcksURL=http://localhost:8080/api/ \
61-
--keycloakClientId=microcks-serviceaccount \
62-
--keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 \
63-
--waitFor=3sec
64-
[...]
65-
MicrocksClient got status for test "5c1781cf6310d94f8169384e" - success: false, inProgress: true
66-
MicrocksTester waiting for 2 seconds before checking again.
67-
MicrocksClient got status for test "5c1781cf6310d94f8169384e" - success: true, inProgress: false
68-
Full TestResult details are available here: http://localhost:8080/#/tests/5c1781cf6310d94f8169384e
22+
### Usage
23+
```bash
24+
microcks [command] [flags]
6925
```
7026

71-
#### Advanced options
72-
73-
The `test` command provides additional flags for advanced usages and options:
74-
75-
* `--verbose` allows to dump on standard output all the HTTP requests and responses,
76-
* `--insecure` allows to interact with Microcks and Keycloak instances through HTTPS without checking certificates issuer CA,
77-
* `--caCerts=<path1,path2>` allows to specify additional certificates CRT files to add to trusted roots ones,
78-
* `--secretName='<Secret Name>'` is an optional flag specifying the name of a Secret to use for connecting endpoint,
79-
* `--filteredOperations=<JSON>` allows to filter a list of operations to launch a test for,
80-
* `--operationsHeaders=<JSON>` allows to override some operations headers for the tests to launch,
81-
* `--oAuth2Context=<JSON>` allows specification of an OAuth2 grant flow to execute before launching the test (starts with Microcks version `1.8.0`).
27+
### Availabel Commands
28+
| Command | Description | Documentation |
29+
| ------------ | -------------------------------------------------------- | ----------------------------------------------- |
30+
| `login` | Log in to a Microcks instance using Keycloak credentials | [`login`](documentation/cmd/login.md) |
31+
| `logout` | Log out and remove authentication from a given context | [`logout`](documentation/cmd/logout.md) |
32+
| `context` | Manage CLI contexts (list, use, delete) | [`context`](documentation/cmd/context.md) |
33+
| `start` | Start a local Microcks instance via Docker/Podman | [`start`](documentation/cmd/start.md) |
34+
| `stop` | Stop a local Microcks instance | [`stop`](documentation/cmd/stop.md) |
35+
| `import` | Import API spec files from local filesystem | [`import`](documentation/cmd/import.md) |
36+
| `import-url` | Import API spec files directly from a remote URL | [`import-url`](documentation/cmd/import-url.md) |
37+
| `test` | Run tests against a deployed API using selected runner | [`test`](documentation/cmd/test.md) |
38+
| `version` | Print Microcks CLI version | [`version`](documentation/cmd/version.md) |
39+
40+
### Options
41+
42+
| Flag | Description |
43+
| ------------------------ | ------------------------------------------- |
44+
| `-h, --help` | help for microck command |
45+
| `--config` | Path to Microcks config file |
46+
| `--microcks-context` | Name of the Microcks context to use |
47+
| `--verbose` | Produce dumps of HTTP exchanges |
48+
| `--insecure-tls` | Allow insecure HTTPS connections |
49+
| `--caCerts` | Comma-separated paths of CA cert files |
50+
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
51+
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
52+
| `--microcksURL` | Microcks API URL |
8253

83-
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.
8454

85-
Here's below an example of using some of this flags:
86-
87-
```sh
88-
$ ./microcks-cli test 'Beer Catalog API:0.9' http://localhost:9090/api/ OPEN_API_SCHEMA \
89-
--microcksURL=http://localhost:8080/api/ \
90-
--keycloakClientId=microcks-serviceaccount \
91-
--keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1 \
92-
--insecure --verbose --waitFor=3sec \
93-
--filteredOperations='["GET /beer", "GET /beer/{name}"]' \
94-
--operationsHeaders='{"globals": [{"name": "x-api-key", "values": "my-values"}], "GET /beer": [{"name": "x-trace-id", "values": "xcvbnsdfghjklm"}]}' \
95-
--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"}'
55+
## Installation
9656

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

101-
### Import command
102-
103-
The `import` command has one argument and common flags with `test` command. You can use it that way:
104-
63+
The resulting binary will be available at:
64+
```bash
65+
/build/dist/microcks
10566
```
106-
microcks-cli import <specificationFile1[:primary],specificationFile2[:primary]>
107-
--microcksURL=<>
108-
--keycloakClientId=<> --keycloakClientSecret=<>
109-
```
110-
111-
The arguments:
112-
113-
* `<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'`
114-
115-
The flags:
11667

117-
* `--microcksURL` for the Microcks API endpoint,
118-
* `--keycloakClientId` for the Keycloak Realm Service Account ClientId,
119-
* `--keycloakClientSecret` for the Keycloak Realm Service Account ClientSecret.
120-
121-
> 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`.
122-
123-
Real life example command and execution:
124-
125-
```sh
126-
$ ./microcks-cli import 'samples/weather-forecast-openapi.yml:true,samples/weather-forecast-postman.json:false' \
127-
--microcksURL=http://localhost:8080/api/ \
128-
--keycloakClientId=microcks-serviceaccount \
129-
--keycloakClientSecret=7deb71e8-8c80-4376-95ad-00a399ee3ca1
130-
Microcks has discovered 'WeatherForecast API:1.1.0'
131-
Microcks has discovered 'WeatherForecast API:1.1.0'
68+
You can move it to a location in your $PATH for global usage, for example:
69+
```bash
70+
sudo mv build/dist/microcks /usr/local/bin/microcks
13271
```
13372

134-
#### Advanced options
135-
136-
The `import` command provides additional flags for advanced usages and options:
137-
138-
* `--verbose` allows to dump on standard output all the HTTP requests and responses,
139-
* `--insecure` allows to interact with Microcks and Keycloak instances through HTTPS without checking certificates issuer CA,
140-
* `--caCerts=<path1,path2>` allows to specify additional certificates CRT files to add to trusted roots ones,
141-
142-
143-
## Installation
14473

14574
### Binary
14675

‎documentation/cmd/context.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
## `microcks context` – Manage CLI Contexts
2+
Switch between, list, or delete configured Microcks CLI contexts.
3+
4+
### Usage
5+
```bash
6+
microcks context [CONTEXT] [flags]
7+
```
8+
9+
### Examples
10+
```bash
11+
# List all available contexts
12+
microcks context/ctx
13+
14+
# Switch to this context
15+
microcks context/ctx http://localhost:8080
16+
17+
# Delete the context
18+
microcks context/ctx http://localhost:8080 --delete/-d
19+
```
20+
### Options
21+
| Flag | Description |
22+
| -------------- | ---------------------------- |
23+
| `-d, --delete` | Delete the specified context |
24+
| `-h, --help` | help for context |
25+
26+
### Options Inherited from Parent Commands
27+
| Flag | Description |
28+
| ------------------------ | ------------------------------------------- |
29+
| `--config` | Path to Microcks config file |
30+
| `--microcks-context` | Name of the Microcks context to use |
31+
| `--verbose` | Produce dumps of HTTP exchanges |
32+
| `--insecure-tls` | Allow insecure HTTPS connections |
33+
| `--caCerts` | Comma-separated paths of CA cert files |
34+
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
35+
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
36+
| `--microcksURL` | Microcks API URL |
37+
38+
39+

‎documentation/cmd/import.md‎

Lines changed: 36 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,43 @@
1-
# Import Command
1+
## `microcks import` – Import API Artifacts into Microcks
2+
Uploads one or more API spec files (e.g., OpenAPI, AsyncAPI, Postman) to the Microcks server and optionally watches them for changes.
23

3-
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.
4+
### Usage
5+
```bash
6+
microcks import <specFile1[:main]>,<specFile2[:main]> [flags]
7+
```
8+
9+
### Examples
10+
```bash
11+
# Import a single artifact (marked as main)
12+
microcks import ./api.yaml
413

5-
📝 Description
14+
# Specify mainArtifact flag for each file
15+
microcks import ./api.yaml:false,./schema.json:true
616

7-
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.
17+
# Import and watch file for changes
18+
microcks import ./api.yaml --watch
819

9-
📌 Usage
10-
```bash
11-
microcks import <specificationFile1[:primary]>,<specificationFile2[:primary]> \
12-
--microcksURL <microcks-api-url> \
13-
--keycloakClientId <client-id> \
14-
--keycloakClientSecret <client-secret> \
15-
[--insecure] \
16-
[--caCerts <cert-paths>] \
17-
[--verbose]
20+
# Import specification to microcks without logining to microcks
21+
microck import ./api.yaml \
22+
--micrcoksURL <microcks-url> \
23+
--keycloakClientId <client-id> \
24+
--keycloakClientSecret <client-secret>
1825
```
19-
Arguments
20-
- `<specificationFile[:primary]>`:
21-
A comma-separated list of specification file paths to import.
22-
Optionally, each file can be suffixed with `:true` or `:false` to indicate whether it's the primary artifact.
2326

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

33-
🧪 Examples
34-
- Basic Import
35-
```bash
36-
microcks import my-api.yaml \
37-
--microcksURL http://localhost:8080/api \
38-
--keycloakClientId my-client \
39-
--keycloakClientSecret my-secret
40-
```
41-
- Import Multiple Files with Primary Indicator
42-
```bash
43-
microcks import openapi.yaml:true,postman.json:false \
44-
--microcksURL https://microcks.example.com/api \
45-
--keycloakClientId my-client \
46-
--keycloakClientSecret my-secret
47-
```
48-
- Using Custom TLS CA Certificates and Verbose Logging
49-
```bash
50-
microcks-cli import spec.yaml \
51-
--microcksURL https://microcks.example.com/api \
52-
--keycloakClientId my-client \
53-
--keycloakClientSecret my-secret \
54-
--caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \
55-
--verbose
56-
```
33+
### Options Inherited from Parent Commands
34+
| Flag | Description |
35+
| ------------------------ | ------------------------------------------- |
36+
| `--config` | Path to Microcks config file |
37+
| `--microcks-context` | Name of the Microcks context to use |
38+
| `--verbose` | Produce dumps of HTTP exchanges |
39+
| `--insecure-tls` | Allow insecure HTTPS connections |
40+
| `--caCerts` | Comma-separated paths of CA cert files |
41+
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
42+
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
43+
| `--microcksURL` | Microcks API URL |

‎documentation/cmd/importURL.md‎

Lines changed: 26 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,34 @@
1-
# ImportURL Command
1+
## `microcks import-url` – Import API Artifacts from URL
2+
Imports API specification files (OpenAPI, AsyncAPI, etc.) hosted at a remote URL into the Microcks server.
23

3-
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.
4-
5-
📝 Description
6-
7-
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.
8-
9-
📌 Usage
4+
### Usage
105
```bash
11-
microcks import-url <url1[:primary]>,<url2[:primary]> \
12-
--microcksURL <microcks-api-url> \
13-
--keycloakClientId <client-id> \
14-
--keycloakClientSecret <client-secret> \
15-
[--insecure] \
16-
[--caCerts <cert-paths>] \
17-
[--verbose]
6+
microcks import-url <specURL1[:main][:secret]>,<specURL2[:main][:secret]> [flags]
187
```
198

20-
Arguments
21-
- `<url[:primary]>`:
22-
A comma-separated list of publicly accessible URLs pointing to specification files.
23-
Optionally, each URL can be suffixed with `:true` or `:false` to mark it as a primary artifact.
24-
25-
26-
| Flag | Type | Required | Description |
27-
|-------------------------|---------|----------|-----------------------------------------------------------------------------|
28-
| `--microcksURL` | string | ✅ | The URL of the Microcks API endpoint. |
29-
| `--keycloakClientId` | string | ✅ | The Keycloak Service Account Client ID for OAuth2 authentication. |
30-
| `--keycloakClientSecret`| string | ✅ | The Keycloak Service Account Client Secret for authentication. |
31-
| `--insecure` | bool | ❌ | Allow insecure TLS connections (e.g., self-signed certs). |
32-
| `--caCerts` | string | ❌ | Comma-separated paths to additional CA certificate files (PEM format). |
33-
| `--verbose` | bool | ❌ | Enable verbose mode to dump HTTP requests and responses to the console. |
34-
35-
🧪 Examples
36-
- Importing from a Single URL
9+
### Example
3710
```bash
38-
microcks import-url https://example.com/api/openapi.yaml \
39-
--microcksURL http://localhost:8080/api \
40-
--keycloakClientId my-client \
41-
--keycloakClientSecret my-secret
42-
```
11+
# Import a single artifact (marked as main)
12+
microcks import-url https://example.com/openapi.yaml
4313

44-
- Importing Multiple Remote Artifacts with Primary Designation
45-
```bash
46-
microcks import-url https://example.com/openapi.yaml:true,https://example.com/postman.json:false \
47-
--microcksURL https://microcks.example.com/api \
48-
--keycloakClientId my-client \
49-
--keycloakClientSecret my-secret
50-
```
14+
# Specify mainArtifact flag for each file
15+
microcks import-url https://example.com/spec1.yaml:true,https://example.com/spec2.yaml:false
5116

52-
- Using Custom TLS CA Certificates and Verbose Logging
53-
```bash
54-
microcks import-url https://mydomain.com/api/spec.yaml \
55-
--microcksURL https://microcks.example.com/api \
56-
--keycloakClientId my-client \
57-
--keycloakClientSecret my-secret \
58-
--caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \
59-
--verbose
17+
# Import specification to microcks without logining to microcks
18+
microck import-url https://example.com/openapi.yaml \
19+
--micrcoksURL <microcks-url> \
20+
--keycloakClientId <client-id> \
21+
--keycloakClientSecret <client-secret>
6022
```
23+
24+
### Options Inherited from Parent Commands
25+
| Flag | Description |
26+
| ------------------------ | ------------------------------------------- |
27+
| `--config` | Path to Microcks config file |
28+
| `--microcks-context` | Name of the Microcks context to use |
29+
| `--verbose` | Produce dumps of HTTP exchanges |
30+
| `--insecure-tls` | Allow insecure HTTPS connections |
31+
| `--caCerts` | Comma-separated paths of CA cert files |
32+
| `--keycloakClientId` | Keycloak Realm Service Account ClientId |
33+
| `--keycloakClientSecret` | Keycloak Realm Service Account ClientSecret |
34+
| `--microcksURL` | Microcks API URL |

0 commit comments

Comments
 (0)