From fe63b0673bee82c355564852d82aaf62fc2ca9a6 Mon Sep 17 00:00:00 2001 From: Harsh4902 Date: Thu, 1 May 2025 22:11:15 +0530 Subject: [PATCH 1/2] fixes#145 Doc: Add documentation for import command Signed-off-by: Harsh4902 --- documentation/cmd/import.md | 56 +++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 documentation/cmd/import.md diff --git a/documentation/cmd/import.md b/documentation/cmd/import.md new file mode 100644 index 0000000..7672f8e --- /dev/null +++ b/documentation/cmd/import.md @@ -0,0 +1,56 @@ +# Import Command + +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. + +๐Ÿ“ Description + +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. + +๐Ÿ“Œ Usage +```bash +microcks import , \ + --microcksURL \ + --keycloakClientId \ + --keycloakClientSecret \ + [--insecure] \ + [--caCerts ] \ + [--verbose] +``` +Arguments +- : +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. | + +๐Ÿงช 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 +``` From 2de2104c21208a297707bb419c9e63d29d3021b0 Mon Sep 17 00:00:00 2001 From: Harsh4902 Date: Tue, 6 May 2025 12:25:00 +0530 Subject: [PATCH 2/2] fixes #145 docs: Add documentation for start and import-url commands Signed-off-by: Harsh4902 --- documentation/cmd/import.md | 8 ++--- documentation/cmd/importURL.md | 60 ++++++++++++++++++++++++++++++++++ documentation/cmd/start.md | 34 +++++++++++++++++++ 3 files changed, 98 insertions(+), 4 deletions(-) create mode 100644 documentation/cmd/importURL.md create mode 100644 documentation/cmd/start.md diff --git a/documentation/cmd/import.md b/documentation/cmd/import.md index 7672f8e..83832b0 100644 --- a/documentation/cmd/import.md +++ b/documentation/cmd/import.md @@ -1,10 +1,10 @@ # Import Command -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. +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. ๐Ÿ“ Description -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. +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. ๐Ÿ“Œ Usage ```bash @@ -17,9 +17,9 @@ microcks import , \ [--verbose] ``` Arguments -- : +- ``: 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. +Optionally, each file can be suffixed with `:true` or `:false` to indicate whether it's the primary artifact. | Flag | Type | Required | Description | |-------------------------|---------|----------|-----------------------------------------------------------------------------| diff --git a/documentation/cmd/importURL.md b/documentation/cmd/importURL.md new file mode 100644 index 0000000..c8b664b --- /dev/null +++ b/documentation/cmd/importURL.md @@ -0,0 +1,60 @@ +# ImportURL Command + +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 +```bash +microcks import-url , \ + --microcksURL \ + --keycloakClientId \ + --keycloakClientSecret \ + [--insecure] \ + [--caCerts ] \ + [--verbose] +``` + +Arguments +- ``: +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 +```bash +microcks import-url https://example.com/api/openapi.yaml \ + --microcksURL http://localhost:8080/api \ + --keycloakClientId my-client \ + --keycloakClientSecret my-secret +``` + +- 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 +``` + +- 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 +``` diff --git a/documentation/cmd/start.md b/documentation/cmd/start.md new file mode 100644 index 0000000..4a073cb --- /dev/null +++ b/documentation/cmd/start.md @@ -0,0 +1,34 @@ +# Start Command + +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. + +๐Ÿ“Œ Usage +```bash +microcks start [flags] +``` + +๐Ÿšฉ Flags +| Flag | Description | Required | Default | +| ---------- | -------------------------------------------------- | -------- | ---------------------------------------------- | +| `--name` | Name of the Microcks container/instance | No | `microcks` | +| `--port` | Host port to expose Microcks | No | `8585` | +| `--image` | Image to use for creating the container | No | `quay.io/microcks/microcks-uber:latest-native` | +| `--rm` | Auto-remove container on exit (like `docker --rm`) | No | `false` | +| `--driver` | Container runtime to use (`docker` or `podman`) | No | `docker` | + + +๐Ÿงช Examples + +Start Microcks with default settings: +```sh +microcks start +``` +Start Microcks on port 9090 using Podman: +```sh +microcks start --port 9090 --driver podman +``` + +Start with a custom container name and image: +```sh +microcks start --name dev-microcks --image custom/microcks:latest +```