Skip to content

Minor docs updates #1304

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
Aug 18, 2023
Merged

Minor docs updates #1304

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
2 changes: 1 addition & 1 deletion docs/src/components/RightSidebar/TableOfContents.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ const TableOfContents: FunctionalComponent<{ headings: MarkdownHeading[] }> = ({
return (
<>
<h2 id={onThisPageID}>On this page</h2>
<ul className="toc" ref={toc}>
<ul className="toc" ref={toc} title="Table of Contents">
{headings
.filter(({ depth }) => depth > 1 && depth < 4)
.map((heading) => (
Expand Down
10 changes: 5 additions & 5 deletions docs/src/content/docs/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ description: Additional info about this project
## Project goals

1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
1. Generate **runtime-free types** for maximum performance.
1. This library does **NOT** validate your schema, there existing libraries for that (like [`redocly lint`](https://redocly.com/docs/cli/commands/lint/)).
1. The generated TypeScript types **must** match your schema as closely as possible (e.g. no renaming to `PascalCase`)
1. This library should never require Java, node-gyp, or some other complex environment to work. This should require Node.js and nothing else.
1. This library will never require a running OpenAPI server to work.
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>).
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>.
1. Generated types should match your original schema as closely as possible, preserving original capitalization, etc.
1. Typegen only needs Node.js to run (no Java, Python, etc.) and works in any environment.
1. Support fetching OpenAPI schemas from files as well as local and remote servers.

## Contributors

Expand Down
14 changes: 10 additions & 4 deletions docs/src/content/docs/openapi-fetch/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,24 @@ description: openapi-fetch About

## Project Goals

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

## Differences from openapi-typescript-fetch
## Differences

### From openapi-typescript-fetch

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

- 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`)
- This library has a more terse syntax (`get(…)`) wheras openapi-typescript-fetch requires chaining (`.path(…).method(…).create()`)
- openapi-typescript-fetch supports middleware whereas this library doesn’t

### From openapi-typescript-codegen

This library is quite different from [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)

## Contributors

This library wouldn’t be possible without all these amazing contributors:
28 changes: 13 additions & 15 deletions docs/src/content/docs/openapi-fetch/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ createClient<paths>(options);

| Name | Type | Description |
| :---------------- | :-------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl` | `string` | Prefix all fetch URLs with this option (e.g. `"https://myapi.dev/v1/"`). |
| `fetch` | `fetch` | Fetch function used for requests (defaults to `globalThis.fetch`) |
| `querySerializer` | QuerySerializer | (optional) Serialize query params for all requests (default: `new URLSearchParams()`) |
| `bodySerializer` | BodySerializer | (optional) Serialize request body object for all requests (default: `JSON.stringify()`) |
| `baseUrl` | `string` | Prefix all fetch URLs with this option (e.g. `"https://myapi.dev/v1/"`) |
| `fetch` | `fetch` | Fetch instance used for requests (default: `globalThis.fetch`) |
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
| (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>) |

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

| Name | Type | Description |
| :---------------- | :---------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params` | ParamsObject | Provide `path` and `query` params from the OpenAPI schema |
| `params.path` | `{ [name]: value }` | Provide all `path` params (params that are part of the URL) |
| `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> |
| `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) |
| `querySerializer` | QuerySerializer | (optional) Serialize query params for this request only (default: `new URLSearchParams()`) |
| `bodySerializer` | BodySerializer | (optional) Serialize request body for this request only (default: `JSON.stringify()`) |
| `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"`) |
| (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>) |
| Name | Type | Description |
| :---------------- | :---------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 |
| `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 |
| `querySerializer` | QuerySerializer | (optional) Provide a [querySerializer](#queryserializer) |
| `bodySerializer` | BodySerializer | (optional) Provide a [bodySerializer](#bodyserializer) |
| `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. |
| (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>) |

### querySerializer

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

### bodySerializer

Similar to [querySerializer](#querySerializer), bodySerializer works for requestBody. You probably only need this when using `multipart/form-data`:
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`:

```ts
const { data, error } = await PUT("/submit", {
Expand Down
2 changes: 1 addition & 1 deletion docs/src/layouts/MainLayout.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ const nextLink: Record<string, Link | undefined> = {
{nextLink[currentPage] && <NextLink href={nextLink[currentPage]!.url}>{nextLink[currentPage]!.text}</NextLink>}
</PageContent>
</div>
<aside id="grid-right" class="sidenav grid-sidebar" title="Table of Contents">
<aside id="grid-right" class="sidenav grid-sidebar">
<RightSidebar headings={headings} githubEditUrl={githubEditUrl} />
</aside>
</main>
Expand Down
43 changes: 14 additions & 29 deletions docs/src/pages/index.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@ import MainLayout from "../layouts/MainLayout.astro";
---

<MainLayout title="openapi-typescript">
<p>Tools for consuming OpenAPI schemas in TypeScript.</p>
<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>
<div class="selection">
<a class="lib lib--ts" href="/introduction">
<img src="/assets/openapi-ts.svg" />
<span>Convert OpenAPI schemas to TypeScript types</span>
<span>Convert OpenAPI schemas to runtime-free TypeScript types</span>
</a>
<a class="lib lib--fetch" href="/openapi-fetch">
<img src="/assets/openapi-fetch.svg" />
<span>Ultra-fast, type-safe fetching using your OpenAPI schema</span>
<span>Fast, type-safe fetcher that uses your OpenAPI schema</span>
</a>
</div>
</MainLayout>
Expand All @@ -20,37 +20,25 @@ import MainLayout from "../layouts/MainLayout.astro";
@use '../tokens' as *;

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

.lib {
align-items: flex-start;
border-radius: 1rem;
border: 2px solid token('color.ui.contrast.10');
color: inherit;
display: flex;
flex-direction: column;
font-size: 1.125rem;
gap: 0.5rem;
line-height: 1.5;
text-decoration: none;
padding: 1rem;
position: relative;

&::after {
border: 3px solid transparent;
border-radius: 1rem;
content: '';
display: none;
height: calc(100% + 2rem);
left: -1rem;
pointer-events: none;
position: absolute;
top: -1rem;
width: calc(100% + 2rem);
}
transition: background-color 50ms linear, border-color 50ms linear;
text-decoration: none;

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

&--ts {
&::after {
&:hover,
&:focus-visible {
background-color: color-mix(in oklab, #{token('color.brand.ts-blue')}, 95% transparent);
border-color: token('color.brand.ts-blue');
}

&:hover::after {
display: block;
}
}

&--fetch {
&::after {
&:hover,
&:focus-visible {
background-color: color-mix(in oklab, #{token('color.brand.fetch-green')}, 95% transparent);
border-color: token('color.brand.fetch-green');
}

&:hover::after {
display: block;
}
}
}
</style>
2 changes: 1 addition & 1 deletion packages/openapi-typescript/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "openapi-typescript",
"description": "Generate TypeScript types from Swagger OpenAPI specs",
"description": "Generate runtime-free TypeScript types from Swagger OpenAPI specs",
"version": "6.5.0",
"author": {
"name": "Drew Powers",
Expand Down