update docs and support locale config

Author: malcolm-kee

docs/openapi-ts/plugins/faker.md

@@ -1,18 +1,229 @@
 ---
 title: Faker
-description: Faker plugin for Hey API. Compatible with all our features.
+description: Generate realistic mock data factories from OpenAPI with the Faker plugin for openapi-ts. Fully compatible with all core features.
 ---
 
 <script setup lang="ts">
-import FeatureStatus from '@components/FeatureStatus.vue';
+import Heading from '@components/Heading.vue';
 </script>
 
-# Faker <span data-badge>vote</span>
-
-<FeatureStatus issueNumber=1485 name="Faker" />
+<Heading>
+  <h1>Faker</h1>
+</Heading>
 
 ### About
 
 [Faker](https://fakerjs.dev) is a popular library that generates fake (but reasonable) data that can be used for things such as unit testing, performance testing, building demos, and working without a completed backend.
 
+The Faker plugin for Hey API generates factory functions from your OpenAPI spec that return realistic mock data using `@faker-js/faker`.
+
+## Features
+
+- seamless integration with `@hey-api/openapi-ts` ecosystem
+- factory functions for reusable schema definitions and operation responses
+- smart property name inference for realistic data (e.g. `email` &rarr; `faker.internet.email()`)
+- constraint and format awareness (min/max, string formats, array bounds)
+- optional property and default value handling
+- dependency injection for custom faker instances (locale, seed)
+- minimal learning curve thanks to extending the underlying technology
+
+## Installation
+
+In your [configuration](/openapi-ts/get-started), add `@faker-js/faker` to your plugins and you'll be ready to generate faker factories. :tada:
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    '@faker-js/faker', // [!code ++]
+  ],
+};
+```
+
+## Output
+
+The Faker plugin will generate the following artifacts, depending on the input specification.
+
+## Definitions
+
+A factory function is generated for every reusable definition from your input.
+
+::: code-group
+
+```ts [example]
+import { faker, type Faker } from '@faker-js/faker';
+
+import type { Bar, Foo } from '../types.gen';
+
+export const fakeFoo = (options?: Options): Foo => ({
+  name: ensureFaker(options).string.sample(),
+  age: ensureFaker(options).number.int({ min: 1, max: 120 }),
+});
+
+export const fakeBar = (options?: Options): Bar =>
+  ensureFaker(options).helpers.arrayElement(['baz', 'qux']);
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: '@faker-js/faker',
+      definitions: true, // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
+You can customize the naming and casing pattern for `definitions` factories using the `.name` and `.case` options.
+
+## Responses
+
+A factory function is generated for operation responses. When an operation has a single success response, the factory is unsuffixed. When multiple responses exist, each factory is suffixed with the status code.
+
+::: code-group
+
+```ts [example]
+// single success response — unsuffixed
+export const fakeCreatePetResponse = (options?: Options): CreatePetResponse => fakePet(options);
+
+// multiple responses — suffixed with status code
+export const fakeGetPetResponse200 = (options?: Options): GetPetResponses[200] => fakePet(options);
+
+export const fakeGetPetResponse404 = (options?: Options): GetPetErrors[404] => fakeError(options);
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: '@faker-js/faker',
+      responses: true, // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
+You can customize the naming and casing pattern for `responses` factories using the `.name` and `.case` options.
+
+## Smart Inference
+
+The plugin infers semantically appropriate faker methods from property names, producing more realistic mock data without requiring explicit schema formats or annotations.
+
+```ts
+// property name "email" → faker.internet.email()
+// property name "firstName" → faker.person.firstName()
+// property name "city" → faker.location.city()
+// property name "id" → faker.string.uuid()
+// property name "age" → faker.number.int({ min: 1, max: 120 })
+```
+
+Ancestor context is also used for disambiguation. For example, `name` under a `User` schema produces `faker.person.fullName()`, while `name` under a `Company` schema produces `faker.company.name()`.
+
+Explicit schema annotations (format, pattern, constraints) always take priority over name-based inference.
+
+## Formats and Constraints
+
+The plugin respects OpenAPI schema formats and constraints to generate appropriately bounded data.
+
+**String formats:**
+
+- `email` &rarr; `faker.internet.email()`
+- `date-time` &rarr; `faker.date.recent().toISOString()`
+- `date` &rarr; `faker.date.recent().toISOString().slice(0, 10)`
+- `uuid` &rarr; `faker.string.uuid()`
+- `uri` / `url` &rarr; `faker.internet.url()`
+- `ipv4` &rarr; `faker.internet.ipv4()`
+- `ipv6` &rarr; `faker.internet.ipv6()`
+- `pattern` &rarr; `faker.helpers.fromRegExp(pattern)`
+
+**Numeric constraints:**
+
+- `minimum` / `maximum` &rarr; `faker.number.int({ min, max })`
+- `exclusiveMinimum` / `exclusiveMaximum` &rarr; adjusted bounds
+
+**String constraints:**
+
+- `minLength` / `maxLength` &rarr; `faker.string.alpha({ length: { min, max } })`
+
+**Array constraints:**
+
+- `minItems` / `maxItems` &rarr; controls count in `faker.helpers.multiple()`
+
+## Optional Properties
+
+Required properties are always included. Optional properties are controlled by the `includeOptional` option at runtime.
+
+```ts
+const user = fakeFoo(); // includes optional properties by default
+const user = fakeFoo({ includeOptional: false }); // excludes optional properties
+const user = fakeFoo({ includeOptional: 0.5 }); // 50% probability per optional property
+```
+
+## Default Values
+
+When a schema defines default values, you can control whether to use them instead of generating fake data via the `useDefault` option.
+
+```ts
+const data = fakeFoo(); // always generates fake data
+const data = fakeFoo({ useDefault: true }); // uses schema defaults when available
+const data = fakeFoo({ useDefault: 0.5 }); // 50% probability of using defaults
+```
+
+## Locale
+
+You can configure the locale for generated faker factories. When set, the generated code imports the faker instance from the locale-specific build of `@faker-js/faker`.
+
+::: code-group
+
+```ts [output]
+import { faker } from '@faker-js/faker/locale/de';
+import type { Faker } from '@faker-js/faker';
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: '@faker-js/faker',
+      locale: 'de', // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
+See the [Faker localization guide](https://fakerjs.dev/guide/localization) for available locales.
+
+## Custom Faker Instance
+
+For runtime locale switching or seeded deterministic output, you can pass your own faker instance via the `faker` option.
+
+```ts
+import { faker } from '@faker-js/faker/locale/de';
+
+faker.seed(42);
+const data = fakeFoo({ faker });
+```
+
+## API
+
+You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/@faker-js/faker/types.ts) interface.
+
 <!--@include: ../../partials/sponsors.md-->

packages/openapi-ts-tests/faker/v1/__snapshots__/3.1.x/faker-basic-locale/@faker-js/faker.gen.ts

@@ -0,0 +1,32 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import type { Faker } from '@faker-js/faker';
+import { faker } from '@faker-js/faker/locale/de';
+
+export type Options = {
+    faker?: Faker;
+    /**
+     * Whether to include optional properties.
+     * Provide a number between 0 and 1 to randomly include based on that probability.
+     * @default true
+     */
+    includeOptional?: boolean | number;
+    /**
+     * Whether to use schema default values instead of generating fake data.
+     * Provide a number between 0 and 1 to randomly use defaults based on that probability.
+     * @default false
+     */
+    useDefault?: boolean | number;
+};
+
+const resolveCondition = (condition: boolean | number, faker: Faker): boolean => condition === true || typeof condition === 'number' && faker.datatype.boolean({ probability: condition });
+
+const ensureFaker = (options?: Options): Faker => options?.faker ?? faker;
+
+export const fakeFoo = (options?: Options) => ({
+    name: ensureFaker(options).string.sample(),
+    age: ensureFaker(options).number.int({ min: 1, max: 120 }),
+    ...!resolveCondition(options?.includeOptional ?? true, ensureFaker(options)) ? {} : { active: ensureFaker(options).datatype.boolean() }
+});
+
+export const fakeBar = (options?: Options) => ensureFaker(options).helpers.arrayElement(['baz', 'qux']);

packages/openapi-ts-tests/faker/v1/test/3.1.x.test.ts

@@ -22,6 +22,14 @@ describe(`OpenAPI ${version}`, () => {
       }),
       description: 'generates faker factories for basic schemas',
     },
+    {
+      config: createConfig({
+        input: 'faker-basic.yaml',
+        output: 'faker-basic-locale',
+        plugins: [{ locale: 'de', name: '@faker-js/faker' }],
+      }),
+      description: 'generates faker factories with locale-specific import',
+    },
     {
       config: createConfig({
         input: 'faker-basic.yaml',

packages/openapi-ts/src/plugins/@faker-js/faker/types.ts

@@ -44,6 +44,14 @@ export type UserConfig = Plugin.Name<'@faker-js/faker'> &
            */
           name?: NameTransformer;
         };
+    /**
+     * Locale for `@faker-js/faker`. When set, the generated import for the
+     * faker instance will use `@faker-js/faker/locale/{locale}` instead of
+     * `@faker-js/faker`.
+     *
+     * @see https://fakerjs.dev/guide/localization
+     */
+    locale?: string;
     /**
      * Configuration for operation response factories.
      *
@@ -85,6 +93,8 @@ export type Config = Plugin.Name<'@faker-js/faker'> &
     case: Casing;
     /** Configuration for reusable schema definitions. */
     definitions: NamingOptions & FeatureToggle;
+    /** Locale for `@faker-js/faker`. */
+    locale?: string;
     /** Configuration for operation response factories. */
     responses: NamingOptions & FeatureToggle;
   };

packages/openapi-ts/src/plugins/@faker-js/faker/v1/plugin.ts

@@ -7,8 +7,12 @@ import type { FakerJsFakerPlugin } from '../types';
 import { createProcessor } from './processor';
 
 export const handlerV1: FakerJsFakerPlugin['Handler'] = ({ plugin }) => {
+  const fakerPackagePath = plugin.config.locale
+    ? `@faker-js/faker/locale/${plugin.config.locale}`
+    : '@faker-js/faker';
+
   plugin.symbol('faker', {
-    external: '@faker-js/faker',
+    external: fakerPackagePath,
     importKind: 'named',
   });
 
@@ -49,7 +53,7 @@ export const handlerV1: FakerJsFakerPlugin['Handler'] = ({ plugin }) => {
   const resolveConditionSlot = plugin.node(null);
 
   // Emit helper: const ensureFaker = (options?: Options): Faker => options?.faker ?? faker
-  const fakerSymbol = plugin.external('@faker-js/faker.faker');
+  const fakerSymbol = plugin.external(`${fakerPackagePath}.faker`);
   const ensureFakerFn = $.func()
     .arrow()
     .param('options', (p) => p.optional().type('Options'))