docs: Type‑Safe Validation Errors & Customize OpenAPI Specification (#173)

* Type‑Safe Validation Errors

* Customizing Operation Objects

* Customizing Operation Objects

* Operation Metadata

* improve

* fix types

Author: dinwwwh

apps/content/docs/advanced/validation-errors.md

@@ -91,3 +91,44 @@ Every [procedure](/docs/procedure) built from `base` now uses these customized v
 :::warning
 Middleware applied before `.input`/`.output` catches validation errors by default, but this behavior can be configured.
 :::
+
+## Type‑Safe Validation Errors
+
+As explained in the [error handling guide](/docs/error-handling#combining-both-approaches), when you throw an `ORPCError` instance, if the `code` and `data` match with the errors defined in the `.errors` method, oRPC will treat it exactly as if you had thrown `errors.[code]` using the type‑safe approach.
+
+```ts twoslash
+import { z } from 'zod'
+import { RPCHandler } from '@orpc/server/fetch'
+// ---cut---
+import { onError, ORPCError, os, ValidationError } from '@orpc/server'
+
+const base = os.errors({
+  INPUT_VALIDATION_FAILED: {
+    data: z.object({
+      issues: z.array(z.object({
+        message: z.string(),
+      })),
+    })
+  },
+})
+
+const ping = base.handler(() => 'ping')
+const pong = base.handler(() => 'pong')
+
+const handler = new RPCHandler({ ping, pong }, {
+  clientInterceptors: [
+    onError((error) => {
+      if (
+        error instanceof ORPCError
+        && error.code === 'BAD_REQUEST'
+        && error.cause instanceof ValidationError
+      ) {
+        throw new ORPCError('INPUT_VALIDATION_FAILED', {
+          data: { issues: error.cause.issues },
+          cause: error.cause,
+        })
+      }
+    })
+  ]
+})
+```

apps/content/docs/openapi/openapi-specification.md

@@ -66,6 +66,28 @@ const specFromRouter = await openAPIGenerator.generate(router, {
 })
 ```
 
+## Operation Metadata
+
+You can enrich your API documentation by specifying operation metadata using the `.route` or `.tag`:
+
+```ts
+const ping = os
+  .route({
+    summary: 'the summary',
+    description: 'the description',
+    deprecated: false,
+    tags: ['tag'],
+    successDescription: 'the success description',
+  })
+  .handler(() => {})
+
+// or append tag for entire router
+
+const router = os.tag('planets').router({
+  // ...
+})
+```
+
 ## File Schema
 
 In the [File Upload/Download](/docs/file-upload-download) guide, `z.instanceof` is used to describe file/blob schemas. However, this method prevents oRPC from recognizing file/blob schema. Instead, use the enhanced file schema approach:
@@ -81,7 +103,41 @@ const InputSchema = z.object({
 })
 ```
 
-## Extending the Specification
+## Customizing Operation Objects
+
+You can also extend the operation object using the `.spec` helper for an `error` or `middleware`:
+
+```ts
+import { oo } from '@orpc/openapi'
+
+const base = os.errors({
+  UNAUTHORIZED: oo.spec({
+    data: z.any(),
+  }, {
+    security: [{ 'api-key': [] }],
+  })
+})
+
+// OR in middleware
+
+const requireAuth = oo.spec(
+  os.middleware(async ({ next, errors }) => {
+    throw new ORPCError('UNAUTHORIZED')
+    return next()
+  }),
+  {
+    security: [{ 'api-key': [] }]
+  }
+)
+```
+
+Any [procedure](/docs/procedure) that includes the use above `errors` or `middleware` will automatically have the defined `security` property applied
+
+:::info
+The `.spec` helper accepts a callback as its second argument, allowing you to override the entire operation object.
+:::
+
+## JSON Schema Customization
 
 If Zod alone does not cover your JSON Schema requirements, you can extend or override the generated schema: