Merge branch 'main' into feature/docs-ja/yoshi2no

Author: yoshi2no

.changeset/hip-years-invite.md

@@ -11,8 +11,135 @@ The types generated by openapi-typescript are universal, and can be used in a va
 
 Fetching data can be done simply and safely using an **automatically-typed fetch wrapper**:
 
-- [openapi-fetch](/openapi-fetch/) (recommended)
-- [openapi-typescript-fetch](https://www.npmjs.com/package/openapi-typescript-fetch) by [@ajaishankar](https://github.com/ajaishankar)
+<details>
+<summary><a href="/openapi-fetch/">openapi-fetch</a> (recommended)</summary>
+
+::: code-group
+
+```ts [test/my-project.ts]
+import createClient from "openapi-fetch";
+import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
+
+const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });
+
+const {
+  data, // only present if 2XX response
+  error, // only present if 4XX or 5XX response
+} = await client.GET("/blogposts/{post_id}", {
+  params: {
+    path: { post_id: "123" },
+  },
+});
+
+await client.PUT("/blogposts", {
+  body: {
+    title: "My New Post",
+  },
+});
+```
+
+:::
+
+</details>
+
+<details>
+<summary><a href="https://www.npmjs.com/package/openapi-typescript-fetch" target="_blank" rel="noreferrer">openapi-typescript-fetch</a> by <a href="https://github.com/ajaishankar" target="_blank" rel="noreferrer">@ajaishankar</a></summary>
+
+::: code-group
+
+```ts [test/my-project.ts]
+import { Fetcher } from 'openapi-typescript-fetch';
+import type { paths } from './my-openapi-3-schema'; // generated by openapi-typescript
+
+const fetcher = Fetcher.for<paths>();
+
+// GET request
+const getBlogPost = fetcher.path('/blogposts/{post_id}').method('get').create();
+
+try {
+  const { status, data } = await getBlogPost({ pathParams: { post_id: '123' } });
+  console.log(data);
+} catch (error) {
+  console.error('Error:', error);
+}
+
+// PUT request
+const updateBlogPost = fetcher.path('/blogposts').method('put').create();
+
+try {
+  await updateBlogPost({ body: { title: 'My New Post' } });
+} catch (error) {
+  console.error('Error:', error);
+}
+```
+
+:::
+
+</details>
+
+<details>
+<summary><a href="https://www.npmjs.com/package/feature-fetch" target="_blank" rel="noreferrer">feature-fetch</a> by <a href="https://github.com/builder-group" target="_blank" rel="noreferrer">builder.group</a></summary>
+
+::: code-group
+
+```ts [test/my-project.ts]
+import { createOpenApiFetchClient } from 'feature-fetch';
+import type { paths } from './my-openapi-3-schema'; // generated by openapi-typescript
+
+// Create the OpenAPI fetch client
+const fetchClient = createOpenApiFetchClient<paths>({
+  prefixUrl: 'https://myapi.dev/v1'
+});
+
+// Send a GET request
+const response = await fetchClient.get('/blogposts/{post_id}', {
+  pathParams: {
+    post_id: '123',
+  },
+});
+
+// Handle the response (Approach 1: Standard if-else)
+if (response.isOk()) {
+  const data = response.value.data;
+  console.log(data); // Handle successful response
+} else {
+  const error = response.error;
+  if (error instanceof NetworkError) {
+    console.error('Network error:', error.message);
+  } else if (error instanceof RequestError) {
+    console.error('Request error:', error.message, 'Status:', error.status);
+  } else {
+    console.error('Service error:', error.message);
+  }
+}
+
+// Send a PUT request
+const putResponse = await fetchClient.put('/blogposts', {
+  body: {
+    title: 'My New Post',
+  },
+});
+
+// Handle the response (Approach 2: Try-catch)
+try {
+  const putData = putResponse.unwrap().data;
+  console.log(putData); // Handle the successful response
+} catch (error) {
+  // Handle the error
+  if (error instanceof NetworkError) {
+    console.error('Network error:', error.message);
+  } else if (error instanceof RequestError) {
+    console.error('Request error:', error.message, 'Status:', error.status);
+  } else {
+    console.error('Service error:', error.message);
+  }
+}
+```
+
+:::
+
+</details>
+
 
 ::: tip
 
@@ -60,6 +187,108 @@ TypeChecking in server environments can be tricky, as you’re often querying da
 
 :::
 
+## Hono with [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
+
+Instead of manually typing each route with generics as in the [Hono example](#hono), [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) wraps around the [Hono router](https://hono.dev/docs/api/routing) to deliver full typesafety and enforce your OpenAPI-Schema with validators. 
+
+::: tip Good To Know
+
+While TypeScript types ensure compile-time safety, they don't enforce runtime schema validation. For runtime compliance, you need to integrate with validation libraries like Zod or Valibot. Although you must define the validation rules manually, they are type-safe to ensure these rules are correctly defined.
+
+:::
+
+::: code-group
+
+```ts [src/router.ts]
+import { createHonoOpenApiRouter } from '@blgc/openapi-router';
+import { Hono } from 'hono';
+import { zValidator } from 'validation-adapters/zod';
+import * as z from 'zod';
+
+import { paths } from './gen/v1'; // OpenAPI-generated types
+import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation
+
+export const router = new Hono();
+export const openApiRouter = createHonoOpenApiRouter<paths>(router);
+
+// GET /pet/{petId}
+openApiRouter.get('/pet/{petId}', {
+  pathValidator: zValidator(
+    z.object({
+      petId: z.number() // Validate that petId is a number
+    })
+  ),
+  handler: (c) => {
+    const { petId } = c.req.valid('param'); // Access validated params
+    return c.json({ name: 'Falko', photoUrls: [] }); 
+  }
+});
+
+// POST /pet
+openApiRouter.post('/pet', {
+  bodyValidator: zValidator(PetSchema), // Validate request body using PetSchema
+  handler: (c) => {
+    const { name, photoUrls } = c.req.valid('json'); // Access validated body data
+    return c.json({ name, photoUrls }); 
+  }
+});
+```
+
+:::
+
+[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore)
+
+## Express with [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
+
+[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) wraps around the [Express router](https://expressjs.com/en/5x/api.html#router) to deliver full typesafety and enforce your OpenAPI-Schema with validators. 
+
+::: tip Good To Know
+
+While TypeScript types ensure compile-time safety, they don't enforce runtime schema validation. For runtime compliance, you need to integrate with validation libraries like Zod or Valibot. Although you must define the validation rules manually, they are type-safe to ensure these rules are correctly defined.
+
+:::
+
+::: code-group
+
+```ts [src/router.ts]
+import { createExpressOpenApiRouter } from '@blgc/openapi-router';
+import { Router } from 'express';
+import * as v from 'valibot';
+import { vValidator } from 'validation-adapters/valibot';
+
+import { paths } from './gen/v1'; // OpenAPI-generated types
+import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation
+
+export const router: Router = Router();
+export const openApiRouter = createExpressOpenApiRouter<paths>(router);
+
+// GET /pet/{petId}
+openApiRouter.get('/pet/{petId}', {
+  pathValidator: vValidator(
+    v.object({
+      petId: v.number() // Validate that petId is a number
+    })
+  ),
+  handler: (req, res) => {
+    const { petId } = req.params; // Access validated params
+    res.send({ name: 'Falko', photoUrls: [] }); 
+  }
+});
+
+// POST /pet
+openApiRouter.post('/pet', {
+  bodyValidator: vValidator(PetSchema), // Validate request body using PetSchema
+  handler: (req, res) => {
+    const { name, photoUrls } = req.body; // Access validated body data
+    res.send({ name, photoUrls }); 
+  }
+});
+```
+
+:::
+
+[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore)
+
 ## Mock-Service-Worker (MSW)
 
 If you are using [Mock Service Worker (MSW)](https://mswjs.io) to define your API mocks, you can use a **small, automatically-typed wrapper** around MSW, which enables you to address conflicts in your API mocks easily when your OpenAPI specification changes. Ultimately, you can have the same level of confidence in your application's API client **and** API mocks.

.changeset/lazy-dancers-push.md

@@ -4,19 +4,20 @@ title: openapi-fetch
 
 <img src="/assets/openapi-fetch.svg" alt="openapi-fetch" width="216" height="40" />
 
-openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs **5 kb** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.
+openapi-fetch is a type-safe fetch client that pulls in your OpenAPI schema. Weighs **6 kb** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.
 
 | Library                    | Size (min) | “GET” request\*            |
 | :------------------------- | ---------: | :------------------------- |
-| openapi-fetch              |     `5 kB` | `300k` ops/s (fastest)     |
-| openapi-typescript-fetch   |     `4 kB` | `150k` ops/s (2× slower)   |
+| openapi-fetch              |     `6 kB` | `300k` ops/s (fastest)     |
+| openapi-typescript-fetch   |     `3 kB` | `300k` ops/s (fastest)     |
+| feature-fetch              |    `15 kB` | `300k` ops/s (fastest)     |
 | axios                      |    `32 kB` | `225k` ops/s (1.3× slower) |
 | superagent                 |    `55 kB` | `50k` ops/s (6× slower)    |
 | openapi-typescript-codegen |   `367 kB` | `100k` ops/s (3× slower)   |
 
 _\* [Benchmarks are approximate](https://github.com/openapi-ts/openapi-typescript/blob/main/packages/openapi-fetch/test/index.bench.js) to just show rough baseline and will differ among machines and browsers. The relative performance between libraries is more reliable._
 
-The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 5 kb package.
+The syntax is inspired by popular libraries like react-query or Apollo client, but without all the bells and whistles and in a 6 kb package.
 
 ::: code-group
 
@@ -55,7 +56,7 @@ Notice there are no generics, and no manual typing. Your endpoint’s request an
 - ✅ No manual typing of your API
 - ✅ Eliminates `any` types that hide bugs
 - ✅ Also eliminates `as` type overrides that can also hide bugs
-- ✅ All of this in a **5 kb** client package 🎉
+- ✅ All of this in a **6 kb** client package 🎉
 
 ## Setup
 
@@ -177,7 +178,9 @@ If you prefer selecting the path as a property, you can create a path based clie
 import { createPathBasedClient } from "openapi-fetch";
 import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
 
-const client = createPathBasedClient<paths>({ baseUrl: "https://myapi.dev/v1" });
+const client = createPathBasedClient<paths>({
+  baseUrl: "https://myapi.dev/v1",
+});
 
 client["/blogposts/{post_id}"].GET({
   params: { post_id: "my-post" },

docs/examples.md

@@ -4,15 +4,16 @@ title: openapi-fetch
 
 <img src="/assets/openapi-fetch.svg" alt="openapi-fetch" width="216" height="40" />
 
-`openapi-fetch`是一个类型安全的`fetch`客户端，用于拉取您的OpenAPI模式。大小为**5 kb**，几乎没有运行时。适用于React、Vue、Svelte或纯JS。
+`openapi-fetch`是一个类型安全的`fetch`客户端，用于拉取您的OpenAPI模式。大小为**6 kb**，几乎没有运行时。适用于React、Vue、Svelte或纯JS。
 
 | 库                         | 大小（最小） | “GET” 请求                  |
 | :------------------------- | -----------: | :-------------------------- |
-| openapi-fetch              |       `5 kB` | `278k` 操作/秒（最快）      |
-| openapi-typescript-fetch   |       `4 kB` | `130k` 操作/秒（2.1× 较慢） |
-| axios                      |      `32 kB` | `217k` 操作/秒（1.3× 较慢） |
-| superagent                 |      `55 kB` | `63k` 操作/秒（4.4× 较慢）  |
-| openapi-typescript-codegen |     `367 kB` | `106k` 操作/秒（2.6× 较慢） |
+| openapi-fetch              |       `6 kB` | `300k` 操作/秒（最快）      |
+| openapi-typescript-fetch   |       `3 kB` | `300k` 操作/秒（最快）      |
+| feature-fetch              |      `15 kB` | `300k` ops/s (fastest)      |
+| axios                      |      `32 kB` | `225k` 操作/秒（1.3× 较慢） |
+| superagent                 |      `55 kB` | `50k` 操作/秒（6× 较慢）    |
+| openapi-typescript-codegen |     `367 kB` | `100k` 操作/秒（3× 较慢）   |
 
 语法灵感来自流行的库，如`react-query`或`Apollo client`，但没有所有这些功能，并且包大小仅为5 kb。
 
@@ -53,7 +54,7 @@ await client.PUT("/blogposts", {
 - ✅ 无需手动输入API
 - ✅ 消除隐藏错误的 `any` 类型
 - ✅ 还消除了可能隐藏错误的 `as` 类型覆盖
-- ✅ 所有这些都在一个 **5 kb** 的客户端包中 🎉
+- ✅ 所有这些都在一个 **6 kb** 的客户端包中 🎉
 
 ## 安装
 

docs/openapi-fetch/index.md

@@ -1,5 +1,16 @@
 # openapi-fetch
 
+## 0.11.1
+
+### Patch Changes
+
+- [#1831](https://github.com/openapi-ts/openapi-typescript/pull/1831) [`091e71a`](https://github.com/openapi-ts/openapi-typescript/commit/091e71ad4bf805be32261a53524f320c2fa42690) Thanks [@SebastienGllmt](https://github.com/SebastienGllmt)! - Add MethodResponse utility type to easily get the return type of an endpoint on a client
+
+- [#1833](https://github.com/openapi-ts/openapi-typescript/pull/1833) [`cec023d`](https://github.com/openapi-ts/openapi-typescript/commit/cec023d3461c79ca355a88366949d0f6382e4e2a) Thanks [@ngraef](https://github.com/ngraef)! - Fix identification of required properties when `strictNullChecks` is disabled
+
+- Updated dependencies [[`cec023d`](https://github.com/openapi-ts/openapi-typescript/commit/cec023d3461c79ca355a88366949d0f6382e4e2a)]:
+  - [email protected]
+
 ## 0.11.0
 
 ### Minor Changes