Skip to content

Updated example docs (because of rename from @blgc/openapi-router to openapi-ts-router) #2080

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jan 3, 2025
Merged

Updated example docs (because of rename from @blgc/openapi-router to openapi-ts-router) #2080

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
cbd5b5e
#main expanded example section (wip)
bennobuilder Aug 3, 2024
089b14f
Merge branch 'openapi-ts:main' into main
bennobuilder Aug 14, 2024
e0290a8
#main updated example section and expanded benchmark
bennobuilder Aug 14, 2024
41bd8af
#main undo dev command change
bennobuilder Aug 14, 2024
f4c28bc
#main fixed pnpm-lock?
bennobuilder Aug 14, 2024
2844c14
#main lint fix
bennobuilder Aug 14, 2024
b014998
Merge branch 'main' of https://github.com/bennobuilder/openapi-typesc…
bennobuilder Jan 1, 2025
43735dd
#main updated example section for `@blgc/openapi-router`
bennobuilder Jan 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 43 additions & 23 deletions docs/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ try {
</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>
<summary><a href="https://www.npmjs.com/package/feature-fetch" target="_blank" rel="noreferrer">feature-fetch</a> by <a href="https://builder.group" target="_blank" rel="noreferrer">builder.group</a></summary>

::: code-group

Expand Down Expand Up @@ -257,26 +257,27 @@ 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)
## Hono with [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-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.
[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) provides full type-safety and runtime validation for your HonoAPI routes by wrapping a [Hono router](https://hono.dev/docs/api/routing):

::: tip Good To Know
::: 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.
While TypeScript ensures compile-time type safety, runtime validation is equally important. `openapi-ts-router` integrates with Zod/Valibot to provide both:
- Types verify your code matches the OpenAPI spec during development
- Validators ensure incoming requests match the spec at runtime

:::

::: code-group

```ts [src/router.ts]
import { createHonoOpenApiRouter } from '@blgc/openapi-router';
import { Hono } from 'hono';
import { createHonoOpenApiRouter } from 'openapi-ts-router';
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
import { PetSchema } from './schemas'; // Custom reusable schema for validation

export const router = new Hono();
export const openApiRouter = createHonoOpenApiRouter<paths>(router);
Expand All @@ -302,41 +303,51 @@ openApiRouter.post('/pet', {
return c.json({ name, photoUrls });
}
});

// TypeScript will error if route/method doesn't exist in OpenAPI spec
// or if response doesn't match defined schema
```

:::

[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore)
[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/hono/petstore)

**Key benefits:**
- Full type safety for routes, methods, params, body and responses
- Runtime validation using Zod/Valibot
- Catches API spec mismatches at compile time
- Zero manual type definitions needed

## Express with [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
## Express with [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-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.
[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) provides full type-safety and runtime validation for your Express API routes by wrapping a [Express router](https://expressjs.com/en/5x/api.html#router):

::: tip Good To Know
::: 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.
While TypeScript ensures compile-time type safety, runtime validation is equally important. `openapi-ts-router` integrates with Zod/Valibot to provide both:
- Types verify your code matches the OpenAPI spec during development
- Validators ensure incoming requests match the spec at runtime

:::

::: 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 { createExpressOpenApiRouter } from 'openapi-ts-router';
import * as z from 'zod';
import { zValidator } from 'validation-adapters/zod';
import { paths } from './gen/v1'; // OpenAPI-generated types
import { PetSchema } from './schemas'; // Custom reusable Zod schema for validation
import { PetSchema } from './schemas'; // Custom reusable 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
pathValidator: zValidator(
z.object({
petId: z.number() // Validate that petId is a number
})
),
handler: (req, res) => {
Expand All @@ -347,17 +358,26 @@ openApiRouter.get('/pet/{petId}', {

// POST /pet
openApiRouter.post('/pet', {
bodyValidator: vValidator(PetSchema), // Validate request body using PetSchema
bodyValidator: zValidator(PetSchema), // Validate request body using PetSchema
handler: (req, res) => {
const { name, photoUrls } = req.body; // Access validated body data
res.send({ name, photoUrls });
}
});

// TypeScript will error if route/method doesn't exist in OpenAPI spec
// or if response doesn't match defined schema
```

:::

[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore)
[Full example](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/express/petstore)

**Key benefits:**
- Full type safety for routes, methods, params, body and responses
- Runtime validation using Zod/Valibot
- Catches API spec mismatches at compile time
- Zero manual type definitions needed

## Mock-Service-Worker (MSW)

Expand Down
18 changes: 9 additions & 9 deletions docs/ja/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ try {
</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>
<summary><a href="https://www.npmjs.com/package/feature-fetch" target="_blank" rel="noreferrer">feature-fetch</a> by <a href="https://builder.group" target="_blank" rel="noreferrer">builder.group</a></summary>

::: code-group

Expand Down Expand Up @@ -262,9 +262,9 @@ export default app;

:::

## Hono と [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
## Hono と [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router)

[Honoの例](#hono) のように、各ルートをジェネリックで手動で型付けする代わりに、[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) は、[Hono router](https://hono.dev/docs/api/routing) をラップして完全な型安全性を提供し、バリデーターを使用してOpenAPIスキーマを強制します。
[Honoの例](#hono) のように、各ルートをジェネリックで手動で型付けする代わりに、[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) は、[Hono router](https://hono.dev/docs/api/routing) をラップして完全な型安全性を提供し、バリデーターを使用してOpenAPIスキーマを強制します。

::: tip 知っておくと良いこと

Expand All @@ -275,7 +275,7 @@ TypeScriptの型はコンパイル時の安全性を保証しますが、実行
::: code-group

```ts [src/router.ts]
import { createHonoOpenApiRouter } from "@blgc/openapi-router";
import { createHonoOpenApiRouter } from "openapi-ts-router";
import { Hono } from "hono";
import { zValidator } from "validation-adapters/zod";
import * as z from "zod";
Expand Down Expand Up @@ -311,11 +311,11 @@ openApiRouter.post("/pet", {

:::

[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/hono/petstore)
[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/hono/petstore)

## Express と [`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router)
## Express と [`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router)

[`@blgc/openapi-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-router) は、[Express ルーター](https://expressjs.com/en/5x/api.html#router) をラップして、完全な型安全性を提供し、バリデーターを使用して OpenAPI スキーマを強制します。
[`openapi-ts-router`](https://github.com/builder-group/community/tree/develop/packages/openapi-ts-router) は、[Express ルーター](https://expressjs.com/en/5x/api.html#router) をラップして、完全な型安全性を提供し、バリデーターを使用して OpenAPI スキーマを強制します。

::: tip 知っておくと良いこと

Expand All @@ -326,7 +326,7 @@ TypeScriptの型はコンパイル時の安全性を保証しますが、実行
::: code-group

```ts [src/router.ts]
import { createExpressOpenApiRouter } from "@blgc/openapi-router";
import { createExpressOpenApiRouter } from "openapi-ts-router";
import { Router } from "express";
import * as v from "valibot";
import { vValidator } from "validation-adapters/valibot";
Expand Down Expand Up @@ -362,7 +362,7 @@ openApiRouter.post("/pet", {

:::

[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-router/express/petstore)
[完全な例](https://github.com/builder-group/community/tree/develop/examples/openapi-ts-router/express/petstore)

## Mock-Service-Worker (MSW)

Expand Down
Loading