Skip to content

feat: add operationId, tag rules, and envelope-aware response splitting#51

Merged
Arkptz merged 19 commits into
mainfrom
feat/operationid-tags-envelope
May 28, 2026
Merged

feat: add operationId, tag rules, and envelope-aware response splitting#51
Arkptz merged 19 commits into
mainfrom
feat/operationid-tags-envelope

Conversation

@Arkptz

@Arkptz Arkptz commented May 28, 2026

Copy link
Copy Markdown
Owner

Summary

Adds three backwards-compatible features to generate:

1. operationId generation (--operation-id-strategy)

Derives stable camelCase operationIds from HTTP method + path template so openapi-generator-cli produces readable Rust method names:

GET /api/v1/users           → listUsers
GET /api/v1/users/{id}      → getUser
POST /api/v1/users          → createUser
GET /api/v1/contract/fair_price/{symbol} → getFairPrice
POST /api/v1/private/order/place         → placeOrder

Flags: --operation-id-strategy {none,path,template}, --operation-id-overrides <yaml>, --operation-id-template <tmpl>

2. Regex-based tag rules (--tag-rules)

Assigns one tag per operation via a YAML rules file (first-match-wins). Tags are used by openapi-generator to split operations into separate source files:

rules:
  - match: "^/api/v1/contract/"
    tag: Contract
  - match: "^/api/v1/private/"
    tag: Private
default: Market

Flags: --tag-strategy {legacy,none,path-segment,rules}, --tag-rules <yaml>, --tag-segment-index <N>

3. Envelope-aware response splitting (--envelope-discriminator)

MEXC and similar exchange APIs always return HTTP 200 with a success boolean discriminator. This flag splits captured bodies into per-operation {OperationId}Success schemas and a shared components/schemas/ApiError, connected via oneOf + discriminator annotation:

mitm2openapi generate ... \
  --operation-id-strategy path \
  --tag-rules tag-rules.yaml \
  --envelope-discriminator success

Flags: --envelope-discriminator <field>, --envelope-error-shape <yaml>, --envelope-success-component-suffix <string>

4. Deterministic output

Sorts all paths and component schemas alphabetically before serialization so diffs are byte-stable across runs.

Backwards Compatibility

All new flags default to the v0.6.0 behaviour — snapshot test tests/snapshot_compat.rs enforces byte-identical output when no new flags are passed.

Tests

  • 306 unit tests (including 9 tag_rules + 17 operation_id + 8 envelope tests)
  • 1 snapshot test (byte-identical backwards-compat guard)
  • 2 end-to-end integration tests (all 3 features combined, and no-flags backward compat)
  • cargo clippy --all-targets -- -D warnings clean

New files

  • src/tag_rules.rs — regex-based tag matching module
  • src/operation_id.rs — camelCase operationId derivation + collision resolution
  • src/envelope.rs — discriminator-based response splitting

Arkptz added 19 commits May 27, 2026 20:06
…elope

test(integration): add end-to-end test for operationId, tags, and envelope
@Arkptz Arkptz merged commit 5ec187c into main May 28, 2026
14 checks passed
@Arkptz Arkptz deleted the feat/operationid-tags-envelope branch May 28, 2026 13:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant