Skip to content

Commit f71f4fc

Browse files
drwpowdrwpow
authored
Minor docs updates (#1304)
1 parent 691eb32 commit f71f4fc

File tree

7 files changed

+45
-56
lines changed

7 files changed

+45
-56
lines changed

‎docs/src/components/RightSidebar/TableOfContents.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ const TableOfContents: FunctionalComponent<{ headings: MarkdownHeading[] }> = ({
6767
return (
6868
<>
6969
<h2 id={onThisPageID}>On this page</h2>
70-
<ul className="toc" ref={toc}>
70+
<ul className="toc" ref={toc} title="Table of Contents">
7171
{headings
7272
.filter(({ depth }) => depth > 1 && depth < 4)
7373
.map((heading) => (

‎docs/src/content/docs/about.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,11 @@ description: Additional info about this project
2323
## Project goals
2424

2525
1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
26-
1. Generate **runtime-free types** for maximum performance.
27-
1. This library does **NOT** validate your schema, there existing libraries for that (like [`redocly lint`](https://redocly.com/docs/cli/commands/lint/)).
28-
1. The generated TypeScript types **must** match your schema as closely as possible (e.g. no renaming to `PascalCase`)
29-
1. This library should never require Java, node-gyp, or some other complex environment to work. This should require Node.js and nothing else.
30-
1. This library will never require a running OpenAPI server to work.
26+
1. Generated types should be statically-analyzable and runtime-free (with minor exceptions like <a href="https://www.typescriptlang.org/docs/handbook/enums.html" target="_blank" rel="noopener noreferrer">enums</a>).
27+
1. Don’t validate schemas; there are existing libraries for that like <a href="https://redocly.com/docs/cli/commands/lint/" target="_blank" rel="noopener noreferrer">Redocly</a>.
28+
1. Generated types should match your original schema as closely as possible, preserving original capitalization, etc.
29+
1. Typegen only needs Node.js to run (no Java, Python, etc.) and works in any environment.
30+
1. Support fetching OpenAPI schemas from files as well as local and remote servers.
3131

3232
## Contributors
3333

‎docs/src/content/docs/openapi-fetch/about.md

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,24 @@ description: openapi-fetch About
55

66
## Project Goals
77

8-
1. Infer types automatically from OpenAPI schemas **without generics** (or, only the absolute minimum needed)
9-
2. Respect the native Fetch API while reducing boilerplate (such as `await res.json()`)
10-
3. Be as small and light as possible
8+
1. Types should be strict and inferred automatically from OpenAPI schemas with the absolute minimum number of generics needed.
9+
2. Respect the native Fetch API while reducing boilerplate (such as `await res.json()`).
10+
3. Be as light and performant as possible.
1111

12-
## Differences from openapi-typescript-fetch
12+
## Differences
13+
14+
### From openapi-typescript-fetch
1315

1416
This library is identical in purpose to [openapi-typescript-fetch](https://github.com/ajaishankar/openapi-typescript-fetch), but has the following differences:
1517

1618
- This library has a built-in `error` type for `3xx`/`4xx`/`5xx` errors whereas openapi-typescript-fetch throws exceptions (requiring you to wrap things in `try/catch`)
1719
- This library has a more terse syntax (`get(…)`) wheras openapi-typescript-fetch requires chaining (`.path(…).method(…).create()`)
1820
- openapi-typescript-fetch supports middleware whereas this library doesn’t
1921

22+
### From openapi-typescript-codegen
23+
24+
This library is quite different from [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)
25+
2026
## Contributors
2127

2228
This library wouldn’t be possible without all these amazing contributors:

‎docs/src/content/docs/openapi-fetch/api.md

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@ createClient<paths>(options);
1313

1414
| Name | Type | Description |
1515
| :---------------- | :-------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16-
| `baseUrl` | `string` | Prefix all fetch URLs with this option (e.g. `"https://myapi.dev/v1/"`). |
17-
| `fetch` | `fetch` | Fetch function used for requests (defaults to `globalThis.fetch`) |
18-
| `querySerializer` | QuerySerializer | (optional) Serialize query params for all requests (default: `new URLSearchParams()`) |
19-
| `bodySerializer` | BodySerializer | (optional) Serialize request body object for all requests (default: `JSON.stringify()`) |
16+
| `baseUrl` | `string` | Prefix all fetch URLs with this option (e.g. `"https://myapi.dev/v1/"`) |
17+
| `fetch` | `fetch` | Fetch instance used for requests (default: `globalThis.fetch`) |
18+
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
19+
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
2020
| (Fetch options) | | Any valid fetch option (`headers`, `mode`, `cache`, `signal` …) (<a href="https://developer.mozilla.org/en-US/docs/Web/API/fetch#options" target="_blank" rel="noopener noreferrer">docs</a>) |
2121

2222
## Fetch options
@@ -27,16 +27,14 @@ The following options apply to all request methods (`.GET()`, `.POST()`, etc.)
2727
client.get("/my-url", options);
2828
```
2929

30-
| Name | Type | Description |
31-
| :---------------- | :---------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
32-
| `params` | ParamsObject | Provide `path` and `query` params from the OpenAPI schema |
33-
| `params.path` | `{ [name]: value }` | Provide all `path` params (params that are part of the URL) |
34-
| `params.query` | `{ [name]: value }` | Provide all `query params (params that are part of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/URL/searchParams" target="_blank" rel="noopener noreferrer">searchParams</a> |
35-
| `body` | `{ [name]:value }` | The <a href="https://spec.openapis.org/oas/latest.html#request-body-object" target="_blank" rel="noopener noreferrer">requestBody</a> data, if needed (PUT/POST/PATCH/DEL only) |
36-
| `querySerializer` | QuerySerializer | (optional) Serialize query params for this request only (default: `new URLSearchParams()`) |
37-
| `bodySerializer` | BodySerializer | (optional) Serialize request body for this request only (default: `JSON.stringify()`) |
38-
| `parseAs` | `"json"` \| `"text"` \| `"arrayBuffer"` \| `"blob"` \| `"stream"` | Parse the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Response/body" target="_blank" rel="noopener noreferrer">response body</a>, with `"stream"` skipping processing altogether (default: `"json"`) |
39-
| (Fetch options) | | Any valid fetch option (`headers`, `mode`, `cache`, `signal` …) (<a href="https://developer.mozilla.org/en-US/docs/Web/API/fetch#options" target="_blank" rel="noopener noreferrer">docs</a>) |
30+
| Name | Type | Description |
31+
| :---------------- | :---------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
32+
| `params` | ParamsObject | <a href="https://swagger.io/specification/#parameter-locations" target="_blank" rel="noopener noreferrer">path</a> and <a href="https://swagger.io/specification/#parameter-locations" target="_blank" rel="noopener noreferrer">query</a> params for the endpoint |
33+
| `body` | `{ [name]:value }` | <a href="https://spec.openapis.org/oas/latest.html#request-body-object" target="_blank" rel="noopener noreferrer">requestBody</a> data for the endpoint |
34+
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
35+
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
36+
| `parseAs` | `"json"` \| `"text"` \| `"arrayBuffer"` \| `"blob"` \| `"stream"` | (optional) Parse the response using <a href="https://developer.mozilla.org/en-US/docs/Web/API/Response#instance_methods" target="_blank" rel="noopener noreferrer">a built-in instance method</a> (default: `"json"`). `"stream"` skips parsing altogether and returns the raw stream. |
37+
| (Fetch options) | | Any valid fetch option (`headers`, `mode`, `cache`, `signal`, …) (<a href="https://developer.mozilla.org/en-US/docs/Web/API/fetch#options" target="_blank" rel="noopener noreferrer">docs</a>) |
4038

4139
### querySerializer
4240

@@ -63,7 +61,7 @@ const { data, error } = await GET("/search", {
6361

6462
### bodySerializer
6563

66-
Similar to [querySerializer](#querySerializer), bodySerializer works for requestBody. You probably only need this when using `multipart/form-data`:
64+
Similar to [querySerializer](#querySerializer), bodySerializer allows you to customize how the requestBody is serialized if you don’t want the default <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify" target="_blank">JSON.stringify()</a> behavior. You probably only need this when using `multipart/form-data`:
6765

6866
```ts
6967
const { data, error } = await PUT("/submit", {

‎docs/src/layouts/MainLayout.astro

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ const nextLink: Record<string, Link | undefined> = {
113113
{nextLink[currentPage] && <NextLink href={nextLink[currentPage]!.url}>{nextLink[currentPage]!.text}</NextLink>}
114114
</PageContent>
115115
</div>
116-
<aside id="grid-right" class="sidenav grid-sidebar" title="Table of Contents">
116+
<aside id="grid-right" class="sidenav grid-sidebar">
117117
<RightSidebar headings={headings} githubEditUrl={githubEditUrl} />
118118
</aside>
119119
</main>

‎docs/src/pages/index.astro

Lines changed: 14 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,15 @@ import MainLayout from "../layouts/MainLayout.astro";
33
---
44

55
<MainLayout title="openapi-typescript">
6-
<p>Tools for consuming OpenAPI schemas in TypeScript.</p>
6+
<p>Consume type-safe <a href="https://spec.openapis.org/oas/latest.html" target="_blank" rel="noopener noreferrer">OpenAPI 3.0 and 3.1 schemas</a> in TypeScript.</p>
77
<div class="selection">
88
<a class="lib lib--ts" href="/introduction">
99
<img src="/assets/openapi-ts.svg" />
10-
<span>Convert OpenAPI schemas to TypeScript types</span>
10+
<span>Convert OpenAPI schemas to runtime-free TypeScript types</span>
1111
</a>
1212
<a class="lib lib--fetch" href="/openapi-fetch">
1313
<img src="/assets/openapi-fetch.svg" />
14-
<span>Ultra-fast, type-safe fetching using your OpenAPI schema</span>
14+
<span>Fast, type-safe fetcher that uses your OpenAPI schema</span>
1515
</a>
1616
</div>
1717
</MainLayout>
@@ -20,37 +20,25 @@ import MainLayout from "../layouts/MainLayout.astro";
2020
@use '../tokens' as *;
2121

2222
.selection {
23-
border-top: 1px solid token('color.ui.border');
2423
display: grid;
2524
gap: 2rem;
2625
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
27-
margin-top: 2.5rem !important;
28-
padding-top: 1.5rem;
2926
}
3027

3128
.lib {
3229
align-items: flex-start;
30+
border-radius: 1rem;
31+
border: 2px solid token('color.ui.contrast.10');
3332
color: inherit;
3433
display: flex;
3534
flex-direction: column;
3635
font-size: 1.125rem;
3736
gap: 0.5rem;
3837
line-height: 1.5;
39-
text-decoration: none;
38+
padding: 1rem;
4039
position: relative;
41-
42-
&::after {
43-
border: 3px solid transparent;
44-
border-radius: 1rem;
45-
content: '';
46-
display: none;
47-
height: calc(100% + 2rem);
48-
left: -1rem;
49-
pointer-events: none;
50-
position: absolute;
51-
top: -1rem;
52-
width: calc(100% + 2rem);
53-
}
40+
transition: background-color 50ms linear, border-color 50ms linear;
41+
text-decoration: none;
5442

5543
&:hover {
5644
text-decoration: none;
@@ -62,23 +50,20 @@ import MainLayout from "../layouts/MainLayout.astro";
6250
}
6351

6452
&--ts {
65-
&::after {
53+
&:hover,
54+
&:focus-visible {
55+
background-color: color-mix(in oklab, #{token('color.brand.ts-blue')}, 95% transparent);
6656
border-color: token('color.brand.ts-blue');
6757
}
6858

69-
&:hover::after {
70-
display: block;
71-
}
7259
}
7360

7461
&--fetch {
75-
&::after {
62+
&:hover,
63+
&:focus-visible {
64+
background-color: color-mix(in oklab, #{token('color.brand.fetch-green')}, 95% transparent);
7665
border-color: token('color.brand.fetch-green');
7766
}
78-
79-
&:hover::after {
80-
display: block;
81-
}
8267
}
8368
}
8469
</style>

‎packages/openapi-typescript/package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "openapi-typescript",
3-
"description": "Generate TypeScript types from Swagger OpenAPI specs",
3+
"description": "Generate runtime-free TypeScript types from Swagger OpenAPI specs",
44
"version": "6.5.0",
55
"author": {
66
"name": "Drew Powers",

0 commit comments

Comments
 (0)