feat: examples plugin

mrlubos · mrlubos · commit d116eac442d5 · 2026-04-15T13:36:07.000+02:00
diff --git a/.changeset/early-knives-kneel.md b/.changeset/early-knives-kneel.md
@@ -0,0 +1,5 @@
+---
+"@hey-api/openapi-ts": patch
+---
+
+**client**: use `getBaseUrl()` function to determine default value
diff --git a/.changeset/five-pianos-jump.md b/.changeset/five-pianos-jump.md
@@ -0,0 +1,5 @@
+---
+"@hey-api/openapi-ts": patch
+---
+
+**plugin(@hey-api/examples)**: initial release
diff --git a/.changeset/nasty-planes-cry.md b/.changeset/nasty-planes-cry.md
@@ -0,0 +1,5 @@
+---
+"@hey-api/shared": patch
+---
+
+**utils**: export `getBaseUrl()` function
diff --git a/dev/inputs.ts b/dev/inputs.ts
@@ -5,12 +5,15 @@ const specsPath = path.join(__dirname, '..', 'specs');
 export const inputs = {
   circular: path.resolve(specsPath, '3.0.x', 'circular.yaml'),
   full: path.resolve(specsPath, '3.1.x', 'full.yaml'),
+  heyapi: 'hey-api/backend',
   local: 'http://localhost:8000/openapi.json',
+  mockers: path.resolve(specsPath, '3.1.x', 'mockers.yaml'),
   opencode: path.resolve(specsPath, '3.1.x', 'opencode.yaml'),
   petstore:
     'https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml',
   redfish:
     'https://raw.githubusercontent.com/DMTF/Redfish-Publications/refs/heads/main/openapi/openapi.yaml',
+  rpc: path.resolve(specsPath, '3.1.x', 'rpc.yaml'),
   scalar: 'scalar:@scalar/access-service',
   transformers: path.resolve(specsPath, '3.1.x', 'transformers.json'),
   validators: path.resolve(specsPath, '3.1.x', 'validators.yaml'),
diff --git a/packages/openapi-python/src/plugins/types.ts b/packages/openapi-python/src/plugins/types.ts
@@ -4,7 +4,7 @@ export type PluginClientNames =
   | '@hey-api/client-requests'
   | '@hey-api/client-urllib3';
 
-export type PluginMockNames = 'factory_boy' | 'faker' | 'mimesis';
+export type PluginSourceNames = 'factory_boy' | 'faker' | 'mimesis';
 
 export type PluginTransformerNames = never;
 
diff --git a/packages/openapi-ts-tests/main/test/__snapshots__/2.0.x/schema-unknown/client.gen.ts b/packages/openapi-ts-tests/main/test/__snapshots__/2.0.x/schema-unknown/client.gen.ts
@@ -13,4 +13,4 @@ import type { ClientOptions as ClientOptions2 } from './types.gen';
  */
 export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
 
-export const client = createClient(createConfig<ClientOptions2>());
+export const client = createClient(createConfig<ClientOptions2>({ baseUrl: 'api.postmarkapp.com/' }));
diff --git a/packages/openapi-ts-tests/main/test/__snapshots__/2.0.x/servers-host/client.gen.ts b/packages/openapi-ts-tests/main/test/__snapshots__/2.0.x/servers-host/client.gen.ts
@@ -13,4 +13,4 @@ import type { ClientOptions as ClientOptions2 } from './types.gen';
  */
 export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
 
-export const client = createClient(createConfig<ClientOptions2>());
+export const client = createClient(createConfig<ClientOptions2>({ baseUrl: 'foo.com' }));
diff --git a/packages/openapi-ts-tests/orpc/v1/test/3.0.x.test.ts b/packages/openapi-ts-tests/orpc/v1/test/3.0.x.test.ts
@@ -17,15 +17,15 @@ describe(`OpenAPI ${version}`, () => {
   const scenarios = [
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'default',
         plugins: ['orpc', 'zod'],
       }),
       description: 'generate oRPC contracts with Zod schemas',
     },
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'custom-names',
         plugins: [
           'valibot',
diff --git a/packages/openapi-ts-tests/orpc/v1/test/3.1.x.test.ts b/packages/openapi-ts-tests/orpc/v1/test/3.1.x.test.ts
@@ -17,15 +17,15 @@ describe(`OpenAPI ${version}`, () => {
   const scenarios = [
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'default',
         plugins: ['orpc', 'zod'],
       }),
       description: 'generate oRPC contracts with Zod schemas',
     },
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'custom-names',
         plugins: [
           'valibot',
@@ -42,7 +42,7 @@ describe(`OpenAPI ${version}`, () => {
     },
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'contracts-strategy-by-tags',
         plugins: [
           'zod',
@@ -58,7 +58,7 @@ describe(`OpenAPI ${version}`, () => {
     },
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'contracts-strategy-single',
         plugins: [
           'zod',
@@ -75,7 +75,7 @@ describe(`OpenAPI ${version}`, () => {
     },
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'contracts-nesting-id',
         plugins: [
           'zod',
@@ -92,7 +92,7 @@ describe(`OpenAPI ${version}`, () => {
     },
     {
       config: createConfig({
-        input: 'orpc.yaml',
+        input: 'rpc.yaml',
         output: 'contracts-custom-naming',
         plugins: [
           'zod',
diff --git a/packages/openapi-ts/src/index.ts b/packages/openapi-ts/src/index.ts
@@ -47,6 +47,7 @@ declare module '@hey-api/codegen-core' {
       | 'arktype'
       | 'fastify'
       | 'json-schema'
+      | 'msw'
       | 'sdk'
       | 'typescript'
       | 'valibot'
@@ -67,6 +68,7 @@ declare module '@hey-api/shared' {
     '@hey-api/client-next': Plugins.HeyApiClientNext.Types['Types'];
     '@hey-api/client-nuxt': Plugins.HeyApiClientNuxt.Types['Types'];
     '@hey-api/client-ofetch': Plugins.HeyApiClientOfetch.Types['Types'];
+    '@hey-api/examples': Plugins.HeyApiExamples.Types['Types'];
     '@hey-api/schemas': Plugins.HeyApiSchemas.Types['Types'];
     '@hey-api/sdk': Plugins.HeyApiSdk.Types['Types'];
     '@hey-api/transformers': Plugins.HeyApiTransformers.Types['Types'];
@@ -126,6 +128,7 @@ import type {
   HeyApiClientOfetchPlugin,
   OfetchClient as OfetchClientImp,
 } from './plugins/@hey-api/client-ofetch';
+import type { HeyApiExamplesPlugin } from './plugins/@hey-api/examples';
 import type { HeyApiSchemasPlugin } from './plugins/@hey-api/schemas';
 import type { HeyApiSdkPlugin } from './plugins/@hey-api/sdk';
 import type { HeyApiTransformersPlugin } from './plugins/@hey-api/transformers';
@@ -247,6 +250,10 @@ export namespace Plugins {
     export type Types = HeyApiClientOfetchPlugin;
   }
 
+  export namespace HeyApiExamples {
+    export type Types = HeyApiExamplesPlugin;
+  }
+
   export namespace HeyApiSchemas {
     export type Types = HeyApiSchemasPlugin;
   }
diff --git a/packages/openapi-ts/src/plugins/@faker-js/faker/config.ts b/packages/openapi-ts/src/plugins/@faker-js/faker/config.ts
@@ -24,7 +24,7 @@ export const defaultConfig: FakerJsFakerPlugin['Config'] = {
       value: plugin.config.definitions,
     });
   },
-  tags: ['mocker'],
+  tags: ['source'],
 };
 
 /**
diff --git a/packages/openapi-ts/src/plugins/@hey-api/client-core/client.ts b/packages/openapi-ts/src/plugins/@hey-api/client-core/client.ts
@@ -1,31 +1,11 @@
-import { parseUrl } from '@hey-api/shared';
+import { getBaseUrl } from '@hey-api/shared';
 
 import { getTypedConfig } from '../../../config/utils';
 import { clientFolderAbsolutePath } from '../../../generate/client';
 import { $ } from '../../../ts-dsl';
 import type { PluginHandler } from './types';
 import { getClientBaseUrlKey } from './utils';
 
-const resolveBaseUrlString = ({ plugin }: Parameters<PluginHandler>[0]): string | undefined => {
-  const { baseUrl } = plugin.config;
-
-  if (baseUrl === false) {
-    return;
-  }
-
-  if (typeof baseUrl === 'string') {
-    return baseUrl;
-  }
-
-  const { servers } = plugin.context.ir;
-
-  if (!servers) {
-    return;
-  }
-
-  return servers[typeof baseUrl === 'number' ? baseUrl : 0]?.url;
-};
-
 export const createClient: PluginHandler = ({ plugin }) => {
   const clientModule = clientFolderAbsolutePath(getTypedConfig(plugin));
   const symbolCreateClient = plugin.symbol('createClient', {
@@ -47,26 +27,13 @@ export const createClient: PluginHandler = ({ plugin }) => {
       })
     : undefined;
 
-  const defaultVals = $.object();
+  const baseUrl = getBaseUrl(plugin.config.baseUrl ?? true, plugin.context.ir);
 
-  const resolvedBaseUrl = resolveBaseUrlString({
-    plugin: plugin as any,
-  });
-  if (resolvedBaseUrl) {
-    const url = parseUrl(resolvedBaseUrl);
-    if (url.protocol && url.host && !resolvedBaseUrl.includes('{')) {
-      defaultVals.prop(getClientBaseUrlKey(getTypedConfig(plugin)), $.literal(resolvedBaseUrl));
-    } else if (resolvedBaseUrl !== '/' && resolvedBaseUrl.startsWith('/')) {
-      const baseUrl = resolvedBaseUrl.endsWith('/')
-        ? resolvedBaseUrl.slice(0, -1)
-        : resolvedBaseUrl;
-      defaultVals.prop(getClientBaseUrlKey(getTypedConfig(plugin)), $.literal(baseUrl));
-    }
-  }
-
-  if ('throwOnError' in plugin.config && plugin.config.throwOnError) {
-    defaultVals.prop('throwOnError', $.literal(true));
-  }
+  const defaultVals = $.object()
+    .$if(baseUrl, (o, v) => o.prop(getClientBaseUrlKey(getTypedConfig(plugin)), $.literal(v)))
+    .$if('throwOnError' in plugin.config && plugin.config.throwOnError, (o) =>
+      o.prop('throwOnError', $.literal(true)),
+    );
 
   const createConfigParameters = [
     $(symbolCreateConfig)
diff --git a/packages/openapi-ts/src/plugins/@hey-api/client-core/createClientConfig.ts b/packages/openapi-ts/src/plugins/@hey-api/client-core/createClientConfig.ts
@@ -3,7 +3,7 @@ import { clientFolderAbsolutePath } from '../../../generate/client';
 import { $ } from '../../../ts-dsl';
 import type { PluginHandler } from './types';
 
-export const createClientConfigType = ({ plugin }: Parameters<PluginHandler>[0]) => {
+export function createClientConfigType({ plugin }: Parameters<PluginHandler>[0]) {
   const clientModule = clientFolderAbsolutePath(getTypedConfig(plugin));
   const symbolClientOptions = plugin.referenceSymbol({
     category: 'type',
@@ -47,4 +47,4 @@ export const createClientConfigType = ({ plugin }: Parameters<PluginHandler>[0])
         ),
     );
   plugin.node(typeCreateClientConfig);
-};
+}
diff --git a/packages/openapi-ts/src/plugins/@hey-api/examples/config.ts b/packages/openapi-ts/src/plugins/@hey-api/examples/config.ts
@@ -0,0 +1,20 @@
+import { definePluginConfig } from '@hey-api/shared';
+
+// import { handler } from './plugin';
+import type { HeyApiExamplesPlugin } from './types';
+
+export const defaultConfig: HeyApiExamplesPlugin['Config'] = {
+  config: {
+    case: 'camelCase',
+    includeInEntry: false,
+  },
+  // handler,
+  handler: () => {},
+  name: '@hey-api/examples',
+  tags: ['source'],
+};
+
+/**
+ * Type helper for `@hey-api/examples` plugin, returns {@link Plugin.Config} object
+ */
+export const defineConfig = definePluginConfig(defaultConfig);
diff --git a/packages/openapi-ts/src/plugins/@hey-api/examples/index.ts b/packages/openapi-ts/src/plugins/@hey-api/examples/index.ts
@@ -0,0 +1,2 @@
+export { defaultConfig, defineConfig } from './config';
+export type { HeyApiExamplesPlugin } from './types';
diff --git a/packages/openapi-ts/src/plugins/@hey-api/examples/types.ts b/packages/openapi-ts/src/plugins/@hey-api/examples/types.ts
@@ -0,0 +1,24 @@
+import type { Casing } from '@hey-api/shared';
+import type { DefinePlugin, Plugin } from '@hey-api/shared';
+
+export type UserConfig = Plugin.Name<'@hey-api/examples'> &
+  // Plugin.Hooks &
+  Plugin.UserExports & {
+    // Resolvers & {
+    /**
+     * Casing convention for generated names.
+     *
+     * @default 'camelCase'
+     */
+    case?: Casing;
+  };
+
+export type Config = Plugin.Name<'@hey-api/examples'> &
+  // Plugin.Hooks &
+  Plugin.Exports & {
+    // Resolvers & {
+    /** Casing convention for generated names. */
+    case: Casing;
+  };
+
+export type HeyApiExamplesPlugin = DefinePlugin<UserConfig, Config>;
diff --git a/packages/openapi-ts/src/plugins/@hey-api/typescript/shared/clientOptions.ts b/packages/openapi-ts/src/plugins/@hey-api/typescript/shared/clientOptions.ts
@@ -10,7 +10,7 @@ import type { TypeTsDsl } from '../../../../ts-dsl';
 import { $ } from '../../../../ts-dsl';
 import type { HeyApiTypeScriptPlugin } from '../types';
 
-const serverToBaseUrlType = ({ server }: { server: IR.ServerObject }) => {
+function serverToBaseUrlType({ server }: { server: IR.ServerObject }): TypeTsDsl {
   const url = parseUrl(server.url);
 
   if (url.protocol && url.host) {
@@ -24,17 +24,17 @@ const serverToBaseUrlType = ({ server }: { server: IR.ServerObject }) => {
     .add(url.host || $.type('string'))
     .add(url.port ? `:${url.port}` : '')
     .add(url.path || '');
-};
+}
 
-export const createClientOptions = ({
+export function createClientOptions({
   nodeIndex,
   plugin,
   servers,
 }: {
   nodeIndex: number;
   plugin: HeyApiTypeScriptPlugin['Instance'];
   servers: ReadonlyArray<IR.ServerObject>;
-}) => {
+}) {
   const client = getClientPlugin(getTypedConfig(plugin));
 
   const types: Array<TypeTsDsl> = servers.map((server) => serverToBaseUrlType({ server }));
@@ -70,4 +70,4 @@ export const createClientOptions = ({
         .prop(getClientBaseUrlKey(getTypedConfig(plugin)), (p) => p.type($.type.or(...types))),
     );
   plugin.node(node, nodeIndex);
-};
+}
diff --git a/packages/openapi-ts/src/plugins/config.ts b/packages/openapi-ts/src/plugins/config.ts
@@ -9,6 +9,7 @@ import { defaultConfig as heyApiClientKy } from '../plugins/@hey-api/client-ky';
 import { defaultConfig as heyApiClientNext } from '../plugins/@hey-api/client-next';
 import { defaultConfig as heyApiClientNuxt } from '../plugins/@hey-api/client-nuxt';
 import { defaultConfig as heyApiClientOfetch } from '../plugins/@hey-api/client-ofetch';
+import { defaultConfig as heyApiExamples } from '../plugins/@hey-api/examples';
 import { defaultConfig as heyApiSchemas } from '../plugins/@hey-api/schemas';
 import { defaultConfig as heyApiSdk } from '../plugins/@hey-api/sdk';
 import { defaultConfig as heyApiTransformers } from '../plugins/@hey-api/transformers';
@@ -40,6 +41,7 @@ export const defaultPluginConfigs: {
   '@hey-api/client-next': heyApiClientNext,
   '@hey-api/client-nuxt': heyApiClientNuxt,
   '@hey-api/client-ofetch': heyApiClientOfetch,
+  '@hey-api/examples': heyApiExamples,
   '@hey-api/schemas': heyApiSchemas,
   '@hey-api/sdk': heyApiSdk,
   '@hey-api/transformers': heyApiTransformers,
diff --git a/packages/openapi-ts/src/plugins/types.ts b/packages/openapi-ts/src/plugins/types.ts
@@ -7,7 +7,7 @@ export type PluginClientNames =
   | '@hey-api/client-nuxt'
   | '@hey-api/client-ofetch';
 
-export type PluginMockNames = '@faker-js/faker';
+export type PluginSourceNames = '@faker-js/faker' | '@hey-api/examples';
 
 export type PluginTransformerNames = '@hey-api/transformers';
 
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
@@ -144,4 +144,4 @@ export {
   refToName,
   resolveRef,
 } from './utils/ref';
-export { parseUrl } from './utils/url';
+export { getBaseUrl, parseUrl } from './utils/url';
diff --git a/packages/shared/src/plugins/types.ts b/packages/shared/src/plugins/types.ts
@@ -19,7 +19,7 @@ export type PluginNames = keyof PluginConfigMap extends never ? string : keyof P
 
 export type AnyPluginName = PluginNames | AnyString;
 
-type PluginTag = 'client' | 'mocker' | 'sdk' | 'transformer' | 'validator';
+type PluginTag = 'client' | 'handler' | 'sdk' | 'source' | 'transformer' | 'validator';
 
 export type PluginContext = {
   package: Dependency;
diff --git a/packages/shared/src/utils/url.ts b/packages/shared/src/utils/url.ts
diff --git a/specs/3.0.x/rpc.yaml b/specs/3.0.x/rpc.yaml
diff --git a/specs/3.1.x/mockers.yaml b/specs/3.1.x/mockers.yaml
diff --git a/specs/3.1.x/rpc.yaml b/specs/3.1.x/rpc.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@hey-api/openapi-ts": patch
 +---
++
 +**client**: use `getBaseUrl()` function to determine default value