Skip to content

Commit 13ed101

Browse files
Harsh4902Harsh4902
authored
Add documentation for commands with examples (#148)
* fixes#145 Doc: Add documentation for import command Signed-off-by: Harsh4902 <[email protected]> * fixes #145 docs: Add documentation for start and import-url commands Signed-off-by: Harsh4902 <[email protected]> --------- Signed-off-by: Harsh4902 <[email protected]>
1 parent 603e58f commit 13ed101

File tree

3 files changed

+150
-0
lines changed

3 files changed

+150
-0
lines changed

‎documentation/cmd/import.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Import Command
2+
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+
5+
📝 Description
6+
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.
8+
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]
18+
```
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.
23+
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. |
32+
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+
```

‎documentation/cmd/importURL.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# ImportURL Command
2+
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
10+
```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]
18+
```
19+
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
37+
```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+
```
43+
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+
```
51+
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
60+
```

‎documentation/cmd/start.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Start Command
2+
3+
The `start` command allows you to launch a Microcks instance using a container runtime like Docker or Podman. It either starts a new container or resumes a previously created one based on saved configuration.
4+
5+
📌 Usage
6+
```bash
7+
microcks start [flags]
8+
```
9+
10+
🚩 Flags
11+
| Flag | Description | Required | Default |
12+
| ---------- | -------------------------------------------------- | -------- | ---------------------------------------------- |
13+
| `--name` | Name of the Microcks container/instance | No | `microcks` |
14+
| `--port` | Host port to expose Microcks | No | `8585` |
15+
| `--image` | Image to use for creating the container | No | `quay.io/microcks/microcks-uber:latest-native` |
16+
| `--rm` | Auto-remove container on exit (like `docker --rm`) | No | `false` |
17+
| `--driver` | Container runtime to use (`docker` or `podman`) | No | `docker` |
18+
19+
20+
🧪 Examples
21+
22+
Start Microcks with default settings:
23+
```sh
24+
microcks start
25+
```
26+
Start Microcks on port 9090 using Podman:
27+
```sh
28+
microcks start --port 9090 --driver podman
29+
```
30+
31+
Start with a custom container name and image:
32+
```sh
33+
microcks start --name dev-microcks --image custom/microcks:latest
34+
```

0 commit comments

Comments
 (0)