Skip to content

[chore] Docs updates #1579

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 1 commit into from
Mar 5, 2024
Merged

[chore] Docs updates #1579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
6 changes: 6 additions & 0 deletions docs/.vitepress/theme/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,9 +208,15 @@ code {
display: flex;
flex-wrap: wrap;
gap: 2.5rem;
list-style: none;
justify-content: center;
}

.logo-salad-list li {
display: flex;
list-style: none;
}

.logo-salad-list svg {
fill: var(--vp-c-text-1);
width: auto;
Expand Down
2 changes: 1 addition & 1 deletion docs/6.x/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ These 2 projects are unrelated. openapi-typescript-codegen is a Node.js alternat

### vs. tRPC

[tRPC](https://trpc.io/) is an opinionated typesafe framework for both server and client. It demands both your server and client be written in tRPC (which means Node.js for the backend).
[tRPC](https://trpc.io/) is an opinionated type-safe framework for both server and client. It demands both your server and client be written in tRPC (which means Node.js for the backend).

If you fit into this usecase, it’s a great experience! But for everyone else, openapi-typescript (and openapi-fetch) is a more flexible, lower-level solution that can work for any technology choice (or even be incrementally-adopted without any cost).

Expand Down
2 changes: 1 addition & 1 deletion docs/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ These 2 projects are unrelated. openapi-typescript-codegen is a Node.js alternat

### vs. tRPC

[tRPC](https://trpc.io/) is an opinionated typesafe framework for both server and client. It demands both your server and client be written in tRPC (which means Node.js for the backend).
[tRPC](https://trpc.io/) is an opinionated type-safe framework for both server and client. It demands both your server and client be written in tRPC (which means Node.js for the backend).

If you fit into this use case, it’s a great experience! But for everyone else, openapi-typescript (and openapi-fetch) is a more flexible, lower-level solution that can work for any technology choice (or even be incrementally-adopted without any cost).

Expand Down
2 changes: 1 addition & 1 deletion docs/data/contributors.json
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ hero:

features:
- title: Blazing Fast
details: Nothing is faster than instant. Static TypeScript types provide zero runtime performance and zero client weight.
details: Nothing is faster than instant. Static TypeScript types provide zero runtime cost and zero client weight.
- title: Type-safe
details: Use your OpenAPI schema to typecheck your entire codebase with no setup and no tests.
- title: Works anywhere
Expand Down
2 changes: 1 addition & 1 deletion docs/openapi-fetch/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: openapi-fetch

<img src="/assets/openapi-fetch.svg" alt="openapi-fetch" width="216" height="40" />

openapi-fetch is a typesafe 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 **5 kb** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.

| Library | Size (min) | “GET” request |
| :------------------------- | ---------: | :------------------------- |
Expand Down
1 change: 1 addition & 0 deletions docs/scripts/update-contributors.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,7 @@ const OPENAPI_TS_CONTRIBUTORS = [
"hrsh7th",
"davidleger95",
"phk422",
"mzronek",
]),
];

Expand Down
100 changes: 49 additions & 51 deletions docs/zh/openapi-fetch/api.md
View file
Open in desktop

Large diffs are not rendered by default.

23 changes: 10 additions & 13 deletions docs/zh/openapi-fetch/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ await client.PUT("/blogposts", {

`data`和`error`经过类型检查，并将其类型暴露给VS Code（以及任何其他支持TypeScript的IDE）的智能感知。同样，请求`body`也将检查其字段，如果缺少任何必需的参数或存在类型不匹配，则会出错。

`GET()`、`PUT()`、`POST()`等是对原生 [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) 的轻量包装（您可以 [替换为任何调用](/openapi-fetch/zh/api#create-client)）。
`GET()`、`PUT()`、`POST()`等是对原生 [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) 的轻量包装（您可以 [替换为任何调用](/zh/openapi-fetch/api#create-client)）。

请注意，没有泛型，也没有手动类型化。您的端点的请求和响应已自动推断。这对于端点的类型安全性是一个巨大的改进，因为**每个手动断言都可能导致错误**！这消除了以下所有问题：

Expand Down Expand Up @@ -94,7 +94,6 @@ npx openapi-typescript ./path/to/api/v1.yaml -o ./src/lib/api/v1.d.ts
使用 `tsc --noEmit` 来检查类型错误，而不要依赖于您的 linter 或构建命令。没有什么比 TypeScript 编译器本身更能准确地检查类型。
:::


## 基本用法

使用 `openapi-fetch` 而不是传统的代码生成的最大优点是不需要文档。`openapi-fetch` 鼓励使用现有的 OpenAPI 文档，而不是试图找出要导入的函数或该函数需要哪些参数：
Expand All @@ -109,9 +108,7 @@ const client = createClient<paths>({ baseUrl: "https://myapi.dev/v1/" });

const { data, error } = await client.GET("/blogposts/{post_id}", {
params: {
path: { post_id: "my-post"

},
path: { post_id: "my-post" },
query: { version: 2 },
},
});
Expand Down Expand Up @@ -158,16 +155,16 @@ const { data, error } = await client.PUT("/blogposts", {
const { data, error, response } = await client.GET("/url");
```

| 对象 | 响应 |
| :--------- | :----------------------------------------------------------- |
| `data` | 如果 OK 则为 `2xx` 响应；否则为 `undefined` |
| `error` | 如果不是 OK，则为 `5xx`、`4xx` 或 `default` 响应；否则为 `undefined` |
| 对象 | 响应 |
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prettier format noise; no actual changes

| :--------- | :------------------------------------------------------------------------------------------------ |
| `data` | 如果 OK 则为 `2xx` 响应；否则为 `undefined` |
| `error` | 如果不是 OK，则为 `5xx`、`4xx` 或 `default` 响应；否则为 `undefined` |
| `response` | [原始响应](https://developer.mozilla.org/en-US/docs/Web/API/Response) 包含 `status`、`headers` 等 |

## 支持

| 平台 | 支持 |
| :------------- | :----------------------------------------------------------- |
| 平台 | 支持 |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| **浏览器** | [查看 fetch API 支持](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API#browser_compatibility)（在所有主流浏览器中广泛可用） |
| **Node** | >= 18.0.0 |
| **TypeScript** | >= 4.7（建议使用 >= 5.0） |
| **Node** | >= 18.0.0 |
| **TypeScript** | >= 4.7（建议使用 >= 5.0） |
6 changes: 3 additions & 3 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@
"devDependencies": {
"@changesets/changelog-github": "^0.5.0",
"@changesets/cli": "^2.27.1",
"@typescript-eslint/eslint-plugin": "^7.0.1",
"@typescript-eslint/parser": "^7.0.1",
"@typescript-eslint/eslint-plugin": "^7.1.1",
"@typescript-eslint/parser": "^7.1.1",
"del-cli": "^5.1.0",
"eslint": "^8.56.0",
"eslint": "^8.57.0",
"eslint-config-prettier": "^9.1.0",
"eslint-plugin-import": "^2.29.1",
"eslint-plugin-no-only-tests": "^3.1.0",
Expand Down
2 changes: 1 addition & 1 deletion packages/openapi-fetch/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<img src="../../docs/public/assets/openapi-fetch.svg" alt="openapi-fetch" width="216" height="40" />

openapi-fetch is a typesafe fetch client that pulls in your OpenAPI schema. Weighs **4 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 **4 kB** and has virtually zero runtime. Works with React, Vue, Svelte, or vanilla JS.

| Library | Size (min) | “GET” request |
| :------------------------- | ---------: | :------------------------- |
Expand Down
2 changes: 1 addition & 1 deletion packages/openapi-fetch/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "openapi-fetch",
"description": "Fast, typesafe fetch client for your OpenAPI schema. Only 5 kb (min). Works with React, Vue, Svelte, or vanilla JS.",
"description": "Fast, type-safe fetch client for your OpenAPI schema. Only 5 kb (min). Works with React, Vue, Svelte, or vanilla JS.",
"version": "0.9.2",
"author": {
"name": "Drew Powers",
Expand Down
Loading