Skip to content

chore(snip): clarify help text to describe both remove and filter modes #192

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

Open
bflad wants to merge 1 commit into
base: main
Choose a base branch
from
+27 −11
Open

chore(snip): clarify help text to describe both remove and filter modes #192

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
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 11 additions & 5 deletions cmd/openapi/commands/openapi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
```
Expand All @@ -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:**

Expand Down
20 changes: 15 additions & 5 deletions cmd/openapi/commands/openapi/snip.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ var (

var snipCmd = &cobra.Command{
Use: "snip <input-file> [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
Expand All @@ -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)
Expand Down Expand Up @@ -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),
Expand Down
Loading