Skip to content

Commit 5f430e3

Browse files
drwpowdrwpow
authored
Migrate docs to Vitepress (#1446)
1 parent 91c8ad4 commit 5f430e3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+1259
-5807
lines changed

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.vitepress/cache
2+
.vitepress/dist

‎docs/.vitepress/config.ts‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import { defineConfig } from "vitepress";
2+
import packageJSON from "../../packages/openapi-typescript/package.json";
3+
4+
// https://vitepress.dev/reference/site-config
5+
export default defineConfig({
6+
title: "OpenAPI TS",
7+
description: "Consume OpenAPI 3.0 & 3.1 schemas in TypeScript",
8+
cleanUrls: true,
9+
/** @see https://vitepress.dev/reference/default-theme-config */
10+
themeConfig: {
11+
siteTitle: false,
12+
logo: "/assets/openapi-ts.svg",
13+
nav: [
14+
{
15+
text: "Versions",
16+
items: [
17+
{ text: "7.x", link: "/introduction" },
18+
{ text: "6.x", link: "/6.x/introduction" },
19+
],
20+
},
21+
],
22+
sidebar: {
23+
// 6.x docs
24+
"/6.x/": [
25+
{
26+
text: "openapi-typescript (6.x)",
27+
items: [
28+
{ text: "Introduction", link: "/6.x/introduction" },
29+
{ text: "CLI", link: "/6.x/cli" },
30+
{ text: "Node.js API", link: "/6.x/node" },
31+
{ text: "Advanced", link: "/6.x/advanced" },
32+
{ text: "About", link: "/6.x/about" },
33+
],
34+
},
35+
{
36+
text: "openapi-fetch",
37+
items: [
38+
{ text: "Introduction", link: "/openapi-fetch/" },
39+
{ text: "Examples", link: "/openapi-fetch/examples" },
40+
{ text: "API", link: "/openapi-fetch/api" },
41+
{ text: "About", link: "/openapi-fetch/about" },
42+
],
43+
},
44+
],
45+
// default (7.x) docs
46+
"/": [
47+
{
48+
text: "openapi-typescript (7.x)",
49+
items: [
50+
{ text: "Introduction", link: "/introduction" },
51+
{ text: "CLI", link: "/cli" },
52+
{ text: "Node.js API", link: "/node" },
53+
{ text: "Migrating from 6.x", link: "/migration-guide" },
54+
{ text: "Advanced", link: "/advanced" },
55+
{ text: "About", link: "/about" },
56+
],
57+
},
58+
{
59+
text: "openapi-fetch",
60+
items: [
61+
{ text: "Introduction", link: "/openapi-fetch/" },
62+
{ text: "Examples", link: "/openapi-fetch/examples" },
63+
{ text: "API", link: "/openapi-fetch/api" },
64+
{ text: "About", link: "/openapi-fetch/about" },
65+
],
66+
},
67+
],
68+
},
69+
search: {
70+
provider: "algolia",
71+
options: {
72+
appId: "NA92XVKBVS",
73+
apiKey: "4f3ce9ca7edc3b83c209e6656ab29eb8",
74+
indexName: "openapi-ts",
75+
},
76+
},
77+
socialLinks: [
78+
{ icon: "github", link: "https://github.com/drwpow/openapi-typescript" },
79+
],
80+
},
81+
});

‎docs/.vitepress/theme/index.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// https://vitepress.dev/guide/custom-theme
2+
import { h } from "vue";
3+
import type { Theme } from "vitepress";
4+
import DefaultTheme from "vitepress/theme";
5+
import "./style.css";
6+
7+
export default {
8+
extends: DefaultTheme,
9+
Layout: () => {
10+
return h(DefaultTheme.Layout, null, {
11+
// https://vitepress.dev/guide/extending-default-theme#layout-slots
12+
});
13+
},
14+
enhanceApp({ app, router, siteData }) {
15+
// ...
16+
},
17+
} satisfies Theme;

‎docs/.vitepress/theme/style.css‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
/**
2+
* Customize default theme styling by overriding CSS variables:
3+
* https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
4+
*/
5+
6+
/**
7+
* Fonts
8+
*/
9+
10+
@font-face {
11+
font-family: "Geist";
12+
src: url("/assets/GeistVariableVF.woff2") format("woff2");
13+
}
14+
15+
@font-face {
16+
font-family: "Geist Mono";
17+
src: url("/assets/GeistMonoVariableVF.woff2") format("woff2");
18+
}
19+
20+
:root {
21+
--vp-font-family-mono: ui-monospace, "Geist Mono", SFMono-Regular, "SF Mono",
22+
Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
23+
}
24+
25+
/**
26+
* Colors
27+
*
28+
* Each colors have exact same color scale system with 3 levels of solid
29+
* colors with different brightness, and 1 soft color.
30+
*
31+
* - `XXX-1`: The most solid color used mainly for colored text. It must
32+
* satisfy the contrast ratio against when used on top of `XXX-soft`.
33+
*
34+
* - `XXX-2`: The color used mainly for hover state of the button.
35+
*
36+
* - `XXX-3`: The color for solid background, such as bg color of the button.
37+
* It must satisfy the contrast ratio with pure white (#ffffff) text on
38+
* top of it.
39+
*
40+
* - `XXX-soft`: The color used for subtle background such as custom container
41+
* or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
42+
* on top of it.
43+
*
44+
* The soft color must be semi transparent alpha channel. This is crucial
45+
* because it allows adding multiple "soft" colors on top of each other
46+
* to create a accent, such as when having inline code block inside
47+
* custom containers.
48+
*
49+
* - `default`: The color used purely for subtle indication without any
50+
* special meanings attched to it such as bg color for menu hover state.
51+
*
52+
* - `brand`: Used for primary brand colors, such as link text, button with
53+
* brand theme, etc.
54+
*
55+
* - `tip`: Used to indicate useful information. The default theme uses the
56+
* brand color for this by default.
57+
*
58+
* - `warning`: Used to indicate warning to the users. Used in custom
59+
* container, badges, etc.
60+
*
61+
* - `danger`: Used to show error, or dangerous message to the users. Used
62+
* in custom container, badges, etc.
63+
* -------------------------------------------------------------------------- */
64+
65+
:root {
66+
--vp-c-default-1: var(--vp-c-gray-1);
67+
--vp-c-default-2: var(--vp-c-gray-2);
68+
--vp-c-default-3: var(--vp-c-gray-3);
69+
--vp-c-default-soft: var(--vp-c-gray-soft);
70+
71+
--vp-c-brand-1: oklch(0.6 0.22 260);
72+
--vp-c-brand-2: oklch(0.4 0.2 260);
73+
--vp-c-brand-3: oklch(0.5 0.2 260);
74+
--vp-c-brand-soft: oklch(0.6 0.22 260/0.1);
75+
76+
--vp-c-tip-1: var(--vp-c-brand-1);
77+
--vp-c-tip-2: var(--vp-c-brand-2);
78+
--vp-c-tip-3: var(--vp-c-brand-3);
79+
--vp-c-tip-soft: var(--vp-c-brand-soft);
80+
81+
--vp-c-warning-1: var(--vp-c-yellow-1);
82+
--vp-c-warning-2: var(--vp-c-yellow-2);
83+
--vp-c-warning-3: var(--vp-c-yellow-3);
84+
--vp-c-warning-soft: var(--vp-c-yellow-soft);
85+
86+
--vp-c-danger-1: var(--vp-c-red-1);
87+
--vp-c-danger-2: var(--vp-c-red-2);
88+
--vp-c-danger-3: var(--vp-c-red-3);
89+
--vp-c-danger-soft: var(--vp-c-red-soft);
90+
}
91+
92+
/**
93+
* Component: Button
94+
* -------------------------------------------------------------------------- */
95+
96+
:root {
97+
--vp-button-brand-border: transparent;
98+
--vp-button-brand-text: var(--vp-c-white);
99+
--vp-button-brand-bg: var(--vp-c-brand-3);
100+
--vp-button-brand-hover-border: transparent;
101+
--vp-button-brand-hover-text: var(--vp-c-white);
102+
--vp-button-brand-hover-bg: var(--vp-c-brand-2);
103+
--vp-button-brand-active-border: transparent;
104+
--vp-button-brand-active-text: var(--vp-c-white);
105+
--vp-button-brand-active-bg: var(--vp-c-brand-1);
106+
}
107+
108+
/**
109+
* Component: Home
110+
* -------------------------------------------------------------------------- */
111+
112+
:root {
113+
--vp-home-hero-name-color: transparent;
114+
--vp-home-hero-name-background: -webkit-linear-gradient(
115+
120deg,
116+
var(--vp-c-brand-1) 30%,
117+
var(--vp-c-brand-2)
118+
);
119+
120+
--vp-home-hero-image-background-image: linear-gradient(
121+
-45deg,
122+
var(--vp-c-brand-1) 50%,
123+
var(--vp-c-brand-2)
124+
);
125+
--vp-home-hero-image-filter: blur(44px);
126+
}
127+
128+
@media (min-width: 640px) {
129+
:root {
130+
--vp-home-hero-image-filter: blur(56px);
131+
}
132+
}
133+
134+
@media (min-width: 960px) {
135+
:root {
136+
--vp-home-hero-image-filter: blur(68px);
137+
}
138+
}
139+
140+
/**
141+
* Component: Custom Block
142+
* -------------------------------------------------------------------------- */
143+
144+
:root {
145+
--vp-custom-block-tip-border: transparent;
146+
--vp-custom-block-tip-text: var(--vp-c-text-1);
147+
--vp-custom-block-tip-bg: var(--vp-c-brand-soft);
148+
--vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
149+
}
150+
151+
/**
152+
* Component: Algolia
153+
* -------------------------------------------------------------------------- */
154+
155+
.DocSearch {
156+
--docsearch-primary-color: var(--vp-c-brand-1) !important;
157+
}

docs/src/content/docs/v6/about.md renamed to docs/6.x/about.md

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,13 @@ title: About
33
description: Additional info about this project
44
---
55

6+
<script setup>
7+
import { VPTeamMembers } from 'vitepress/theme';
8+
import contributors from '../data/contributors.json';
9+
</script>
10+
11+
# About openapi-typescript
12+
613
## Used by
714

815
- [**Bigcommerce**](https://github.com/bigcommerce/bigcommerce-api-node): Node SDK for the BigCommerce API
@@ -14,7 +21,8 @@ description: Additional info about this project
1421
- [**Lotus**](https://github.com/uselotus/lotus): open source pricing & packaging infra
1522
- [**Jitsu**](https://github.com/jitsucom/jitsu): modern, open source data ingestion / data pipelines
1623
- [**Medusa**](https://github.com/medusajs/medusa): building blocks for digital commerce
17-
- [**Nitro engine**](https://github.com/unjs/nitro): universal web server engine that powers Nuxt
24+
- [**Netlify**](https://netlify.com): the modern development platform
25+
- [**Nuxt**](https://github.com/unjs/nitro): The Intuitive Vue framework
1826
- [**Relevance AI**](https://github.com/RelevanceAI/relevance-js-sdk): build and deploy AI chains
1927
- [**Revolt**](https://github.com/revoltchat/api): open source user-first chat platform
2028
- [**Spacebar**](https://github.com/spacebarchat): a free, open source, self-hostable Discord-compatible chat/voice/video platform
@@ -24,12 +32,30 @@ description: Additional info about this project
2432
## Project goals
2533

2634
1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
27-
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>).
28-
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>.
35+
1. Generated types should be statically-analyzable and runtime-free (with minor exceptions like [enums](https://www.typescriptlang.org/docs/handbook/enums.html).
36+
1. Don’t validate schemas; there are existing libraries for that like [Redocly](https://redocly.com/docs/cli/commands/lint/).
2937
1. Generated types should match your original schema as closely as possible, preserving original capitalization, etc.
3038
1. Typegen only needs Node.js to run (no Java, Python, etc.) and works in any environment.
3139
1. Support fetching OpenAPI schemas from files as well as local and remote servers.
3240

41+
## Differences
42+
43+
### vs. swagger-codegen
44+
45+
openapi-typescript was created specifically to be a lighterweight, easier-to-use alternative to swagger-codegen that doesn’t require the Java runtime or running an OpenAPI server. Nor does it generate heavyweight clientside code. In fact, all the code openapi-typescript generates is **runtime free static types** for maximum performance and minimum client weight.
46+
47+
### vs. openapi-typescript-codegen
48+
49+
These 2 projects are unrelated. openapi-typescript-codegen is a Node.js alternative to the original swagger-codegen, but ends up being the same in practice. openapi-typescript has the same advantage of being **runtime free** whereas openapi-typescript-codegen can generate some pretty heavy bundles, up to `250 kB` or more depending on the schema complexity.
50+
51+
### vs. tRPC
52+
53+
[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).
54+
55+
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).
56+
3357
## Contributors
3458

3559
This library wouldn’t be possible without all these amazing contributors:
60+
61+
<VPTeamMembers size="small" :members="contributors['openapi-typescript']" />

docs/src/content/docs/v6/advanced.md renamed to docs/6.x/advanced.md

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ title: Advanced
33
description: Advanced usage as well as tips, tricks, and best practices
44
---
55

6+
# Advanced usage
7+
68
Advanced usage and various topics.
79

810
## Data fetching
@@ -12,9 +14,11 @@ Fetching data can be done simply and safely using an **automatically-typed fetch
1214
- [openapi-fetch](./openapi-fetch) (recommended)
1315
- [openapi-typescript-fetch](https://www.npmjs.com/package/openapi-typescript-fetch) by [@ajaishankar](https://github.com/ajaishankar)
1416

15-
> ✨ **Tip**
16-
>
17-
> A good fetch wrapper should **never use generics.** Generics require more typing and can hide errors!
17+
::: tip
18+
19+
A good fetch wrapper should **never use generics.** Generics require more typing and can hide errors!
20+
21+
:::
1822

1923
## Testing
2024

@@ -34,8 +38,9 @@ Let’s say we want to write our mocks in the following object structure, so we
3438

3539
Using our generated types we can then infer **the correct data shape** for any given path + HTTP method + status code. An example test would look like this:
3640

37-
```ts
38-
// my-test.test.ts
41+
::: code-group
42+
43+
```ts [my-test.test.ts]
3944
import { mockResponses } from "../test/utils";
4045

4146
describe("My API test", () => {
@@ -71,15 +76,18 @@ describe("My API test", () => {
7176
});
7277
```
7378

79+
:::
80+
7481
_Note: this example uses a vanilla `fetch()` function, but any fetch wrapper—including [openapi-fetch](/openapi-fetch)—could be dropped in instead without any changes._
7582

7683
And the magic that produces this would live in a `test/utils.ts` file that can be copy + pasted where desired (hidden for simplicity):
7784

7885
<details>
7986
<summary>📄 <strong>test/utils.ts</strong></summary>
8087

88+
::: code-group [test/utils.ts]
89+
8190
```ts
82-
// test/utils.ts
8391
import { paths } from "./api/v1/my-schema"; // generated by openapi-typescript
8492

8593
// Settings
@@ -159,7 +167,13 @@ export function findPath(
159167
}
160168
```
161169

162-
> **Additional Explanation** That code is quite above is quite a doozy! For the most part, it’s a lot of implementation detail you can ignore. The `mockResponses(…)` function signature is where all the important magic happens—you’ll notice a direct link between this structure and our design. From there, the rest of the code is just making the runtime work as expected.
170+
:::
171+
172+
::: info Additional Explanation
173+
174+
That code is quite above is quite a doozy! For the most part, it’s a lot of implementation detail you can ignore. The `mockResponses(…)` function signature is where all the important magic happens—you’ll notice a direct link between this structure and our design. From there, the rest of the code is just making the runtime work as expected.
175+
176+
:::
163177

164178
```ts
165179
export function mockResponses(responses: {
@@ -372,7 +386,7 @@ prefixItems:
372386

373387
### Use `$defs` only in object types
374388

375-
<a href="https://json-schema.org/understanding-json-schema/structuring.html#defs" target="_blank" rel="noopener noreferrer">JSONSchema $defs</a> can be used to provide sub-schema definitions anywhere. However, these won’t always convert cleanly to TypeScript. For example, this works:
389+
[JSONSchema $defs](https://json-schema.org/understanding-json-schema/structuring.html#defs) can be used to provide sub-schema definitions anywhere. However, these won’t always convert cleanly to TypeScript. For example, this works:
376390

377391
```yaml
378392
components:

0 commit comments

Comments
 (0)