Merge pull request #3506 from hey-api/docs/zod-valibot-metadata

docs: expand metadata section for zod and valibot

Author: mrlubos

docs/openapi-ts/plugins/valibot.md

@@ -178,7 +178,7 @@ You can customize the naming and casing pattern for `definitions` schemas using
 
 ## Metadata
 
-It's often useful to associate a schema with some additional [metadata](https://valibot.dev/api/metadata/) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
+It's often useful to associate a schema with some additional [metadata](https://valibot.dev/api/metadata/) for documentation, code generation, AI structured outputs, form validation, and other purposes. You can set `metadata` to `true` to attach descriptions to schemas when available.
 
 ::: code-group
 
@@ -207,6 +207,40 @@ export default {
 
 :::
 
+For more control over metadata, you can provide your own function. It receives the source `schema`, the target `node` object, and the `$` builder for populating metadata.
+
+::: code-group
+
+```ts [example]
+export const vFoo = v.pipe(
+  v.string(),
+  v.metadata({
+    hasTitle: false,
+    createdAt: 1735732800000,
+  }),
+);
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'valibot',
+      metadata({ $, node, schema }) {
+        // [!code ++]
+        node.prop('hasTitle', $.literal(Boolean(schema.title))); // [!code ++]
+        node.prop('createdAt', $.literal(Date.now())); // [!code ++]
+      }, // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
 ## Resolvers
 
 You can further customize this plugin's behavior using [resolvers](/openapi-ts/plugins/concepts/resolvers).

docs/openapi-ts/plugins/zod.md

@@ -238,7 +238,7 @@ export default {
 
 ## Metadata
 
-It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
+It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. You can set `metadata` to `true` to attach descriptions to schemas when available.
 
 ::: code-group
 
@@ -264,6 +264,37 @@ export default {
 
 :::
 
+For more control over metadata, you can provide your own function. It receives the source `schema`, the target `node` object, and the `$` builder for populating metadata.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.string().register(z.globalRegistry, {
+  hasTitle: true,
+  createdAt: 1735732800000,
+});
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      metadata({ $, node, schema }) {
+        // [!code ++]
+        node.prop('hasTitle', $.literal(Boolean(schema.title))); // [!code ++]
+        node.prop('createdAt', $.literal(Date.now())); // [!code ++]
+      }, // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
 ## Types
 
 In addition to Zod schemas, you can generate schema-specific types. These can be generated for all schemas or for specific resources.

docs/openapi-ts/plugins/zod/mini.md

@@ -249,7 +249,7 @@ export default {
 
 ## Metadata
 
-It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. If this is your use case, you can set `metadata` to `true` to generate additional metadata about schemas.
+It's often useful to associate a schema with some additional [metadata](https://zod.dev/metadata) for documentation, code generation, AI structured outputs, form validation, and other purposes. You can set `metadata` to `true` to attach descriptions to schemas when available.
 
 ::: code-group
 
@@ -276,6 +276,38 @@ export default {
 
 :::
 
+For more control over metadata, you can provide your own function. It receives the source `schema`, the target `node` object, and the `$` builder for populating metadata.
+
+::: code-group
+
+```ts [example]
+export const zFoo = z.string().register(z.globalRegistry, {
+  hasTitle: true,
+  createdAt: 1735732800000,
+});
+```
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    {
+      name: 'zod',
+      compatibilityVersion: 'mini',
+      metadata({ $, node, schema }) {
+        // [!code ++]
+        node.prop('hasTitle', $.literal(Boolean(schema.title))); // [!code ++]
+        node.prop('createdAt', $.literal(Date.now())); // [!code ++]
+      }, // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
 ## Types
 
 In addition to Zod schemas, you can generate schema-specific types. These can be generated for all schemas or for specific resources.