Skip to content

Migrate OpenAPI clients to Orval with runtime validation #1359

Open

Description

@dgee2

Problem Statement

Menu depends on unmaintained OpenAPI TypeScript generation and HTTP client packages. The website needs a maintained toolchain and runtime contract checks without losing authenticated recipe workflows, useful API errors, or reliable query caching.

Solution

Replace the current generator and client with Orval-generated Vue Query clients, Zod Mini validators and MSW integration. Validate requests and responses against accurate backend OpenAPI contracts, retain the recipe service interface and observable behavior, and verify the real authenticated flow.

User Stories

  1. As a recipe user, I want to sign in and load my recipes, so that I can use my collection.
  2. As a recipe user, I want to switch list scope, so that I can see the appropriate recipes.
  3. As a recipe user, I want to view recipe details, so that I can prepare a recipe.
  4. As a recipe user, I want to create and update recipes, so that I can maintain my collection.
  5. As a recipe user, I want to delete and restore recipes, so that I can manage my collection.
  6. As a recipe user, I want ingredient units to load, so that I can describe ingredients accurately.
  7. As a recipe user, I want changes reflected in relevant views, so that I do not see stale data.
  8. As a recipe user, I want duplicate and validation errors handled as before, so that I can correct input.
  9. As a recipe user, I want safe, understandable failure messages, so that I know when an operation fails.
  10. As a developer, I want typed clients generated from the backend contract, so that API changes surface during development.
  11. As a developer, I want request bodies and path and query parameters validated before dispatch, so that invalid inputs never reach the server.
  12. As a developer, I want valid requests sent without value transformations, so that validation does not alter their meaning.
  13. As a developer, I want successful JSON responses validated before caching, so that malformed data cannot silently enter the UI.
  14. As a developer, I want documented JSON error bodies validated, so that malformed problem details are not trusted.
  15. As a developer, I want invalid error responses to retain their HTTP status, so that conflicts remain distinguishable from transport failures.
  16. As a developer, I want undocumented statuses and media types treated as contract failures, so that contract drift is visible.
  17. As a developer, I want documented empty responses accepted, so that legitimate bodyless outcomes work.
  18. As a developer, I want validation failures to avoid automatic retries, so that deterministic failures do not cause repeated requests.
  19. As a developer, I want generated MSW handlers with deterministic scenarios, so that UI tests are repeatable.
  20. As a developer, I want a real authenticated end-to-end test, so that generated mocks do not hide integration defects.
  21. As a maintainer, I want accurate contracts for every documented operation, so that validation covers the API consistently.
  22. As a maintainer, I want reproducible generation and CI checks, so that generated clients stay aligned with the backend.
  23. As a maintainer, I want useful diagnostics without credentials or payload logging, so that failures can be investigated safely.

Implementation Decisions

  • Replace the direct openapi-typescript and openapi-fetch dependencies with Orval-generated Vue Query clients and Zod 4 Mini schemas. Generate MSW handlers for Storybook and unit tests; use deterministic scenario data and override handlers for errors and edge cases.
  • Keep the existing recipe service interface and preserve reactive scopes, query keys, cache isolation, invalidation, deletion and restore semantics. Integrate generated clients behind that boundary.
  • Retain the runtime API base URL and acquire an Auth0 bearer token asynchronously for every request. Verify token failures and concurrent requests. The OpenAPI document declares a bearer scheme but does not currently apply security requirements; do not assume generated auth is configured automatically.
  • Generate schemas and explicitly validate every schema-described request body and path/query input before dispatch. Reject invalid requests without sending them. Preserve original values for valid outgoing requests; retain existing form and server validation.
  • Validate every documented JSON success and error body before consumption or caching. Permit stripping extra response properties. Accept documented bodyless responses. Reject undocumented statuses and media types as contract failures, preserving HTTP status when available.
  • Preserve existing HTTP error behavior for valid problem details. For malformed error bodies retain HTTP status, discard untrusted details, and surface a generic validation failure. Do not automatically retry validation failures; preserve existing retry behavior for other failures.
  • Give users the existing generic error experience for validation failures. Keep diagnostics useful for development and tests without logging payloads, bearer tokens or credentials.
  • Ensure every operation in the OpenAPI document has an accurate contract for applicable inputs and actual responses, including explicit bodyless outcomes. Correct verified schema inaccuracies and document verified authentication, authorization, validation, conflict and server error outcomes; do not invent business rules or assume every response has a body.
  • Orval Fetch validation excludes some responses, and a custom mutator can bypass generated validation. Verify that authentication, error mapping and request and response validation actually run; add explicit validation where generation does not provide it. Generating schemas alone does not validate traffic.
  • Update generation, dependency management, CI and relevant project instructions so the backend OpenAPI document remains the source of truth and client/schema/mock generation is reproducible. Verify generated operation naming and collisions because current operations lack operation IDs.

Testing Decisions

  • Prefer behavioral tests at the existing recipe service boundary: test observable requests, responses, cache behavior and errors instead of generator internals. Use existing recipe service and component tests as prior art, retaining the real Vue Query wiring.
  • Cover recipe operations, list scopes and ingredient units; cache isolation, invalidation, deletion and restoration; bearer injection and runtime base URL; valid request values and invalid body/path/query rejection before dispatch.
  • Cover valid and invalid JSON successes and errors, parsed output including extra-property stripping, documented bodyless responses, undocumented statuses/media types, malformed error details and preserved status, generic user-facing failures, and no validation retries. Verify token failures and that payloads and credentials are not logged.
  • Verify generated coverage of every documented operation and cases including required and optional fields, nullability, enums, arrays and path/query parameters. Verify backend contract changes against actual endpoint behavior.
  • Exercise deterministic generated MSW handlers and overrides in unit tests and Storybook. Run generation, frontend type checking, build, lint, unit and Storybook tests, relevant backend tests, and the required real Auth0/Aspire end-to-end recipe flow. Record blocked prerequisites separately from passed checks.

Out of Scope

  • New recipe features, unrelated business rule changes, replacing Auth0 or replacing Vue Query.
  • Mocking the authenticated full-stack E2E flow or weakening assertions.
  • Inventing backend guarantees that cannot be verified or unrelated schema redesign.

Further Notes

Verify the selected Orval release against Menu's actual OpenAPI document and Zod Mini output before finalizing integration. Generated validators can transform parsed response data; test output as well as parse success. Prove runtime validation and error paths with behavioral tests.

References: https://orval.dev/docs/reference/configuration/output/ ; https://orval.dev/docs/guides/zod/ ; https://orval.dev/docs/guides/vue-query/ ; https://orval.dev/docs/guides/msw/ .

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified and ready for an agent

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions