Skip to content

feat: add --enrichments overlay for operationId-keyed metadata#53

Merged
Arkptz merged 5 commits into
mainfrom
feat/enrichments
May 30, 2026
Merged

feat: add --enrichments overlay for operationId-keyed metadata#53
Arkptz merged 5 commits into
mainfrom
feat/enrichments

Conversation

@Arkptz

@Arkptz Arkptz commented May 28, 2026

Copy link
Copy Markdown
Owner

Summary

Adds --enrichments <PATH> (alias -e) to mitm2openapi generate. The flag loads a YAML overlay keyed by operationId and applies human-written metadata to the auto-generated spec — after build, before write.

What it does

# enrichments.yaml
info:
  description: Reverse-engineered MEXC web API.

operations:
  getFairPrice:
    summary: Get fair price for a futures contract
    description: Returns the mark price used for liquidation calculations.
    x-requires-auth: false
    x-rate-limit: "10/s"
    x-error-codes:
      - code: 401
        message: Not logged in
    responses:
      "200":
        description: Fair price payload

components:
  schemas:
    ApiError:
      description: MEXC envelope error response.
mitm2openapi generate ... \
  --operation-id-strategy path \
  --enrichments enrichments.yaml

Merge semantics

Scope Rule
info.* Overlay wins per-key
operations.<opId>.summary, description, deprecated Overlay wins
operations.<opId>.tags Overlay replaces entire list
operations.<opId>.x-* Passed through verbatim
operations.<opId>.responses.<status>.description Overlay wins
components.schemas.<name>.description Overlay wins (properties untouched)
Unknown operationId Warning (error under --strict)

Constraints

  • Requires --operation-id-strategy to be set (not none)
  • Overlay file max 10 MiB
  • Only numeric response status codes in overlay
  • No deep merge of response schemas

Tests

  • 8 unit tests in src/enrichments.rs (TDD: RED → GREEN)
  • 5 CLI integration tests in tests/enrichments_cli.rs
  • All existing tests pass (snapshot_compat, e2e, etc.)
  • cargo clippy --all-targets -- -D warnings clean

New files

  • src/enrichments.rs — overlay types + apply_enrichments() + unit tests
  • tests/enrichments_cli.rs — CLI integration tests

@Arkptz Arkptz merged commit 4067050 into main May 30, 2026
14 checks passed
@Arkptz Arkptz deleted the feat/enrichments branch May 30, 2026 17:09
This was referenced May 30, 2026
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