From cd6c667ee267f409cdf7a6a35f9cc135f5091046 Mon Sep 17 00:00:00 2001
From: Yusuke Wada <yusuke@kamawada.com>
Date: Thu, 19 Dec 2024 10:26:01 +0900
Subject: [PATCH] docs(zod-openapi): add docs for lacking proper Content-Type
 in a request (#893)

---
 packages/zod-openapi/README.md | 76 +++++++++++++++++++++++++++++++---
 1 file changed, 71 insertions(+), 5 deletions(-)

diff --git a/packages/zod-openapi/README.md b/packages/zod-openapi/README.md
index bbb80298..1289daed 100644
--- a/packages/zod-openapi/README.md
+++ b/packages/zod-openapi/README.md
@@ -52,6 +52,7 @@ const UserSchema = z
 ```
 
 > [!TIP]
+>
 > `UserSchema` schema will be registered as `"#/components/schemas/User"` refs in the OpenAPI document.
 > If you want to register the schema as referenced components, use `.openapi()` method.
 
@@ -114,6 +115,71 @@ You can start your app just like you would with Hono. For Cloudflare Workers and
 export default app
 ```
 
+> [!IMPORTANT]
+> The request must have the proper `Content-Type` to ensure the validation. For example, if you want to validate a JSON body, the request must have the `Content-Type` to `application/json` in the request. Otherwise, the value of `c.req.valid('json')` will be `{}`.
+>
+> ```ts
+> import { createRoute, z, OpenAPIHono } from '@hono/zod-openapi'
+>
+> const route = createRoute({
+>   method: 'post',
+>   path: '/books',
+>   request: {
+>     body: {
+>       content: {
+>         'application/json': {
+>           schema: z.object({
+>             title: z.string(),
+>           }),
+>         },
+>       },
+>     },
+>   },
+>   responses: {
+>     200: {
+>       description: 'Success message',
+>     },
+>   },
+> })
+>
+> const app = new OpenAPIHono()
+>
+> app.openapi(route, (c) => {
+>   const validatedBody = c.req.valid('json')
+>   return c.json(validatedBody) // validatedBody is {}
+> })
+>
+> const res = await app.request('/books', {
+>   method: 'POST',
+>   body: JSON.stringify({ title: 'foo' }),
+>   // The Content-Type header is lacking.
+> })
+>
+> const data = await res.json()
+> console.log(data) // {}
+> ```
+>
+> If you want to force validation of requests that do not have the proper `Content-Type`, set the value of `request.body.required` to `true`.
+>
+> ```ts
+> const route = createRoute({
+>   method: 'post',
+>   path: '/books',
+>   request: {
+>     body: {
+>       content: {
+>         'application/json': {
+>           schema: z.object({
+>             title: z.string(),
+>           }),
+>         },
+>       },
+>       required: true, // <== add
+>     },
+>   },
+> })
+> ```
+
 ### Handling Validation Errors
 
 Validation errors can be handled as follows:
@@ -241,7 +307,10 @@ You can generate OpenAPI v3.1 spec using the following methods:
 
 ```ts
 app.doc31('/docs', { openapi: '3.1.0', info: { title: 'foo', version: '1' } }) // new endpoint
-app.getOpenAPI31Document({ openapi: '3.1.0', info: { title: 'foo', version: '1' } }) // schema object
+app.getOpenAPI31Document({
+  openapi: '3.1.0',
+  info: { title: 'foo', version: '1' },
+}) // schema object
 ```
 
 ### The Registry
@@ -285,10 +354,7 @@ const route = createRoute({
   request: {
     params: ParamsSchema,
   },
-  middleware: [
-    prettyJSON(),
-    cache({ cacheName: 'my-cache' })
-  ] as const, // Use `as const` to ensure TypeScript infers the middleware's Context.
+  middleware: [prettyJSON(), cache({ cacheName: 'my-cache' })] as const, // Use `as const` to ensure TypeScript infers the middleware's Context.
   responses: {
     200: {
       content: {