In full-stack web applications, frontend models can easily drift out of sync with backend APIs when types are manually redefined or left untyped. By integrating OpenAPI schema generators into the build pipeline, client applications can consume authoritative backend models directly in their Vue components.

In my recent contribution to GitLab's Contributors Platform (MR !3218, closing Issue #868), I converted the CurrentYearTable leaderboard component to TypeScript.

Here is an architectural walkthrough of how we typed props using generated OpenAPI contracts, applied the withDefaults macro, and constructed tests using model factories.

1. The Challenge: Generic Array Props

In the original implementation, CurrentYearTable.vue received leaderboard records using generic JavaScript options:

<!-- Before (JavaScript) --> <script setup> import { computed } from 'vue'; import ContributorsTable from '~/common/components/ContributorsTable.vue'; const props = defineProps({ contributors: { type: Array, required: true, }, fromDate: { type: String, default: '', }, toDate: { type: String, default: '', }, }); const filterData = computed(() => ({ fromDate: props.fromDate, toDate: props.toDate, })); </script> 

While functional, type: Array gave zero insight into what properties a contributor record contained (such as user handles, merged MR counts, or bonus points). If the backend API renamed or removed a property, the frontend would fail silently at runtime.

2. Deriving Prop Types from OpenAPI Specs

Rather than hand-crafting a duplicate Contributor interface that could drift over time, the project generates TypeScript contracts directly from openapi.yaml.

In CurrentYearTable.vue, we imported GetApiV1LeaderboardResponse and indexed its records:

<!-- After (TypeScript) --> <script setup lang="ts"> import { computed } from 'vue'; import type { GetApiV1LeaderboardResponse } from '~/api/generated'; import ContributorsTable from '~/common/components/ContributorsTable.vue'; const props = withDefaults(defineProps<{ contributors: GetApiV1LeaderboardResponse['records']; fromDate?: string; toDate?: string; }>(), { fromDate: '', toDate: '', }); const filterData = computed(() => ({ fromDate: props.fromDate, toDate: props.toDate, })); </script> <template> <ContributorsTable :contributors="contributors" :filter-data="filterData" /> </template> 

Why this is a best practice:

  1. Single Source of Truth: The TypeScript type GetApiV1LeaderboardResponse['records'] is generated directly from the backend Rails API definition. If an API contract changes, vue-tsc immediately flags any breaking changes across all views.
  2. withDefaults Macro: Provides idiomatic default values for optional string props (fromDate?: string, toDate?: string) without runtime object overhead.

3. Writing Resilient Specs with Model Factories (ADR 005)

Per the project's architectural guidelines (ADR 005: Model Factories in Specs), test fixtures should not be hard-coded object literals with incomplete shapes. Instead, tests use factory functions that populate complete, valid schema defaults.

In CurrentYearTable.spec.ts:

import type { VueWrapper } from '@vue/test-utils'; import { shallowMount } from '@vue/test-utils'; import ContributorsTable from '~/common/components/ContributorsTable.vue'; import { createLeaderboardContributor } from '~/spec/factories/leaderboard'; import CurrentYearTable from './CurrentYearTable.vue'; // Factory generates a valid, complete OpenAPI leaderboard record const mockContributor = createLeaderboardContributor(); let wrapper: VueWrapper; const createWrapper = (props = {}) => { wrapper = shallowMount(CurrentYearTable, { props: { contributors: [mockContributor], ...props, }, }); }; const findContributorsTable = () => wrapper.findComponent(ContributorsTable); it('renders ContributorsTable with contributors and default filterData', () => { createWrapper(); expect(findContributorsTable().props('contributors')).toEqual([mockContributor]); expect(findContributorsTable().props('filterData')).toEqual({ fromDate: '', toDate: '', }); }); it('renders ContributorsTable with custom fromDate and toDate in filterData', () => { createWrapper({ fromDate: '2026-01-01', toDate: '2026-12-31', }); expect(findContributorsTable().props('filterData')).toEqual({ fromDate: '2026-01-01', toDate: '2026-12-31', }); }); 

Using createLeaderboardContributor() ensures that our test mocks strictly adhere to the OpenAPI schema without breaking when new fields are introduced.

Key Takeaways

  1. Leverage Generated API Types: Import types directly from OpenAPI or GraphQL code-generators (Response['key']) to eliminate manual duplication and catch breaking API updates.
  2. Use withDefaults(defineProps<{ ... }>(), { ... }): The standard Vue 3 pattern for combining compile-time type definitions with default prop values.
  3. Adopt Model Factories in Tests: Test helpers like createLeaderboardContributor() ensure test mocks always reflect production API contracts.

Check out the merged Merge Request on GitLab:

👉 GitLab Contributors MR !3218

Author: Manish Kumar

GitLab: @manishpatel00