From aad9edd5a2f490c07ee977b9680177ec6c91fa90 Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Fri, 27 Mar 2026 15:15:46 -0400 Subject: [PATCH] chore(snip): clarify help text to describe both remove and filter modes --- README.md | 2 +- cmd/openapi/commands/openapi/README.md | 16 +++++++++++----- cmd/openapi/commands/openapi/snip.go | 20 +++++++++++++++----- 3 files changed, 27 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 7872536..1d94d28 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,7 @@ The CLI provides four main command groups: - `localize` - Localize an OpenAPI specification by copying external references to a target directory - `optimize` - Optimize an OpenAPI specification by deduplicating inline schemas - `sanitize` - Remove unwanted elements from an OpenAPI specification - - `snip` - Remove selected operations from an OpenAPI specification (interactive or CLI) + - `snip` - Remove or filter operations in an OpenAPI specification (interactive or CLI) - `upgrade` - Upgrade an OpenAPI specification to the latest supported version - `validate` - Validate an OpenAPI specification document - `query` - Query an OpenAPI specification using the [oq pipeline language](./oq/README.md) to answer structural and semantic questions about schemas and operations diff --git a/cmd/openapi/commands/openapi/README.md b/cmd/openapi/commands/openapi/README.md index 39147f1..c5415c3 100644 --- a/cmd/openapi/commands/openapi/README.md +++ b/cmd/openapi/commands/openapi/README.md @@ -1078,7 +1078,7 @@ What the explorer provides: ### `snip` -Remove selected operations from an OpenAPI specification and automatically clean up unused components. +Remove or filter operations in an OpenAPI specification and automatically clean up unused components. ```bash # Interactive mode - browse and select operations via TUI @@ -1100,6 +1100,12 @@ openapi spec snip --operation /users/{id}:DELETE,/admin:GET ./spec.yaml # CLI mode - mixed approaches openapi spec snip --operationId deleteUser --operation /admin:GET ./spec.yaml +# CLI mode - filter to only specific operations (remove everything else) +openapi spec snip --keepOperationId getUser --keepOperationId listUsers ./spec.yaml + +# CLI mode - filter by path:method +openapi spec snip --keepOperation /users:GET,/users/{id}:GET ./spec.yaml + # Write in-place (CLI mode only) openapi spec snip -w --operation /internal/debug:GET ./spec.yaml ``` @@ -1116,10 +1122,10 @@ openapi spec snip -w --operation /internal/debug:GET ./spec.yaml **Command-Line Mode** (operation flags specified): -- Remove operations specified via flags without UI -- Supports `--operationId` for operation IDs -- Supports `--operation` for path:method pairs -- Both flags support comma-separated values or multiple flags +- **Remove mode** (`--operationId`, `--operation`): remove the specified operations +- **Filter mode** (`--keepOperationId`, `--keepOperation`): filter the spec down to only the specified operations, removing everything else +- Remove and filter flags cannot be combined +- All flags support comma-separated values or multiple flags **What snip does:** diff --git a/cmd/openapi/commands/openapi/snip.go b/cmd/openapi/commands/openapi/snip.go index 19a3a96..ce720b6 100644 --- a/cmd/openapi/commands/openapi/snip.go +++ b/cmd/openapi/commands/openapi/snip.go @@ -24,8 +24,8 @@ var ( var snipCmd = &cobra.Command{ Use: "snip [output-file]", - Short: "Remove operations from an OpenAPI specification", - Long: `Remove selected operations from an OpenAPI specification and clean up unused components. + Short: "Remove or filter operations in an OpenAPI specification", + Long: `Remove or filter operations in an OpenAPI specification and clean up unused components. Stdin is supported in CLI mode — either pipe data directly or use '-' explicitly: cat spec.yaml | openapi spec snip --operationId deleteUser @@ -37,12 +37,16 @@ This command can operate in two modes: Launch a terminal UI to browse and select operations for removal. - Navigate with j/k or arrow keys - Press Space to select/deselect operations - - Press 'a' to select all, 'A' to deselect all + - Press 'a' to select all, 'A' to deselect all - Press 'w' to write the result - Press 'q' or Esc to cancel -2. Command-Line Mode (--operationId or --operation flags): - Remove operations specified via flags without launching the UI. +2. Command-Line Mode (flags specified): + Remove or filter operations specified via flags without launching the UI. + - Remove mode (--operationId, --operation): remove the specified operations. + - Filter mode (--keepOperationId, --keepOperation): filter the spec down to + only the specified operations, removing everything else. + Remove and filter flags cannot be combined. Output options: - No output file: writes to stdout (pipe-friendly) @@ -71,6 +75,12 @@ Examples: # CLI mode - mixed operation IDs and path:method openapi spec snip --operationId deleteUser --operation /admin:GET ./spec.yaml + # CLI mode - filter to only specific operations (remove everything else) + openapi spec snip --keepOperationId getUser --keepOperationId listUsers ./spec.yaml + + # CLI mode - filter by path:method + openapi spec snip --keepOperation /users:GET,/users/{id}:GET ./spec.yaml + # CLI mode - write to stdout for piping openapi spec snip --operation /internal/debug:GET ./spec.yaml > ./public-spec.yaml`, Args: stdinOrFileArgs(1, 2),