feat: response/request examples, enhanced path params, OPTIONS filter, redaction

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- *(cli)* add `--skip-options` flag to filter OPTIONS requests (discover + generate)
+- *(cli)* add `--param-regex` flag for custom path parameter detection (discover)
+- *(cli)* add `--max-examples` flag to cap examples per endpoint (generate, default 5)
+- *(cli)* add `--redact-patterns` flag for regex-based value redaction (generate)
+- *(cli)* add `--redact-fields` flag for field-name-based redaction (generate)
+- *(discover)* enhanced path parameterization: UPPER_CASE slugs, hex strings, base58, cross-request variability
+- *(generate)* response/request examples stored as named OpenAPI examples
+- *(generate)* request body schema merging via oneOf for multiple captures
+
 ## [0.5.2](https://github.com/Arkptz/mitm2openapi/compare/v0.5.1...v0.5.2) - 2026-04-24
 
 ### Fixed

Cargo.toml

@@ -42,6 +42,8 @@ uuid = { version = "1", features = ["v4"] }
 rmp-serde = "1"
 globset = "0.4"
 tempfile = "3"
+brotli = "7"
+flate2 = "1"
 
 [dev-dependencies]
 proptest = "1"

README.md

@@ -33,6 +33,9 @@ Credit to [@alufers](https://github.com/alufers) for the original tool that pion
 - **Two-format support** — mitmproxy flow dumps (v19/v20/v21) and HAR 1.2
 - **Two-step workflow** — `discover` finds endpoints, you curate, `generate` emits clean OpenAPI 3.0
 - **Glob filters** — `--exclude-patterns` and `--include-patterns` for automated pipelines
+- **Response examples** — captured bodies stored as named OpenAPI examples with `--max-examples` cap
+- **Smart parameterization** — detects UUIDs, hex, base58, UPPER_CASE slugs, and cross-request variability
+- **Redaction** — `--redact-patterns` and `--redact-fields` scrub sensitive data from examples
 - **Error recovery** — skips corrupt flows, continues processing
 - **Auto-detection** — heuristic format detection from file content
 - **Battle-tested** — integration tests against Swagger Petstore and OWASP crAPI with `oasdiff` verification

book/src/introduction.md

@@ -30,6 +30,9 @@ unattended pipelines.
 - **Resource limits** — configurable caps prevent denial-of-service on untrusted input
 - **Strict mode** — treat warnings as errors for CI gates
 - **Structured reports** — `--report` outputs machine-readable JSON processing summaries
+- **Response examples** — captured request/response bodies stored as named OpenAPI examples
+- **Smart parameterization** — detects UUIDs, hex strings, base58, UPPER_CASE slugs, and cross-request variability
+- **Redaction** — `--redact-patterns` and `--redact-fields` scrub sensitive data from examples
 - **Battle-tested** — integration tests against Swagger Petstore and OWASP crAPI
 - **Cross-platform** — Linux, macOS, Windows pre-built binaries
 

book/src/usage/cli-reference.md

@@ -3,7 +3,7 @@
 <!-- toc -->
 
 ```admonish warning
-This reference was last synced with `mitm2openapi --help` at version 0.5.1.
+This reference was last synced with `mitm2openapi --help` at version 0.6.0.
 If you notice a flag missing from your local `--help` output, the tool may be ahead of these
 docs. [Open an issue](https://github.com/Arkptz/mitm2openapi/issues/new) to prompt an update.
 ```
@@ -35,6 +35,8 @@ mitm2openapi discover [OPTIONS] -i <INPUT> -o <OUTPUT> -p <PREFIX>
 | `--allow-symlinks` | off | Allow symlinked input files |
 | `--strict` | off | Treat warnings as errors (exit code 2) |
 | `--report <PATH>` | | Write structured JSON processing report |
+| `--skip-options` | off | Filter out OPTIONS requests from output |
+| `--param-regex <PATTERN>` | | Custom regex for path parameter detection |
 
 ## `mitm2openapi generate`
 
@@ -73,6 +75,10 @@ mitm2openapi generate [OPTIONS] -i <INPUT> -t <TEMPLATES> -o <OUTPUT> -p <PREFIX
 | `--allow-symlinks` | off | Allow symlinked input files |
 | `--strict` | off | Treat warnings as errors (exit code 2) |
 | `--report <PATH>` | | Write structured JSON processing report |
+| `--skip-options` | off | Filter out OPTIONS requests from output |
+| `--max-examples <N>` | `5` | Maximum examples per endpoint per status code |
+| `--redact-patterns <PATTERNS>` | | Comma-separated regex patterns to redact from examples |
+| `--redact-fields <FIELDS>` | | Comma-separated field names to redact from examples |
 
 ## Common flag details
 

book/src/usage/pipeline.md

@@ -66,8 +66,24 @@ named parameters:
 | `/api/users/42`, `/api/users/99` | `/api/users/{id}` |
 | `/api/orders/abc-def-123` | `/api/orders/{id}` |
 
-UUID-like and numeric segments are detected automatically. More complex patterns require
-manual editing of the templates file.
+UUID-like and numeric segments are detected automatically. The following patterns are also
+recognized:
+
+- **UPPER_CASE slugs** — e.g. `BTC_USDT`, `ETH_BTC`
+- **Hex strings** — segments starting with `0x`
+- **Base58 identifiers** — alphanumeric segments 20+ characters long
+- **Cross-request variability** — segments with 3 or more distinct values across requests
+
+For patterns not covered by the built-in heuristics, use `--param-regex` to supply a custom
+regex. Any path segment matching the regex is treated as a parameter:
+
+```bash
+mitm2openapi discover \
+  -i capture.flow \
+  -o templates.yaml \
+  -p "https://api.example.com" \
+  --param-regex '[A-Z]{2,}_[A-Z]{2,}'
+```
 
 ## Step 2: Curate
 
@@ -165,6 +181,43 @@ mitm2openapi generate \
 
 See the [CLI reference](./cli-reference.md) for all available options.
 
+### Response and request examples
+
+The `generate` step captures actual request and response bodies as named examples in the
+OpenAPI spec. Each unique response per endpoint and status code is stored as a separate
+example, up to the limit set by `--max-examples` (default: 5).
+
+When multiple requests hit the same endpoint with different request bodies, the schemas are
+merged using `oneOf` to represent all observed variants.
+
+### Redacting sensitive data
+
+Production captures often contain tokens, passwords, or PII. Use `--redact-patterns` and
+`--redact-fields` to scrub sensitive values from examples before they land in the spec:
+
+```bash
+mitm2openapi generate \
+  -i capture.flow \
+  -t templates.yaml \
+  -o openapi.yaml \
+  -p "https://api.example.com" \
+  --redact-patterns 'eyJ[\w-]+,sk-[a-zA-Z0-9]+' \
+  --redact-fields 'password,token,secret,authorization'
+```
+
+`--redact-patterns` accepts comma-separated regexes matched against string values.
+`--redact-fields` accepts comma-separated field names whose values are replaced with
+`"[REDACTED]"`.
+
+### Filtering OPTIONS requests
+
+Both `discover` and `generate` accept `--skip-options` to exclude HTTP OPTIONS requests
+(typically CORS preflight) from processing:
+
+```bash
+mitm2openapi discover -i capture.flow -o templates.yaml -p "https://api.example.com" --skip-options
+```
+
 ## Worked example
 
 Starting from a mitmproxy capture of a pet store API: