Merge pull request #262 from hey-api/docs/content

chore(docs): update documentation

.editorconfig

@@ -11,5 +11,8 @@ indent_size = 4
 [*.hbs]
 indent_style = tab
 
+[*.md]
+indent_size = 2
+
 [*.yml]
 indent_size = 2

README.md

@@ -8,18 +8,9 @@
 
 `openapi-ts` started as a fork of [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen). We created it after the original project became [unmaintained](https://github.com/ferdikoomen/openapi-typescript-codegen/issues/1276#issuecomment-1302392146) to add support for OpenAPI v3.1. We plan to resolve the most pressing issues in the original project – open an issue if you'd like to prioritise your use case!
 
-## Features
+## Documentation
 
-- Generate TypeScript clients from OpenAPI v2.0, v3.0, and v3.1 specifications
-- Support JSON or YAML input files
-- Handle external references using [JSON Schema $Ref Parser](https://github.com/APIDevTools/json-schema-ref-parser/)
-- Generate Fetch, Node-Fetch, Axios, Angular, or XHR HTTP clients
-- Can be used with CLI, Node.js, or npx
-- Abortable requests through cancellable promise pattern
-
-## Getting Started
-
-Please follow the documentation [here](https://heyapi.vercel.app/).
+Please visit our [website](https://heyapi.vercel.app/) for documentation, guides, migrating, and more.
 
 ## Contributing
 

docs/.vitepress/config/en.ts

@@ -4,16 +4,11 @@ export default defineConfig({
     lang: 'en-US',
     description: 'Turn your OpenAPI specification into a beautiful TypeScript client',
     themeConfig: {
-        nav: [
-            { text: 'Guide', link: '/introduction' },
-        ],
         sidebar: [
             {
-                text: 'Guide',
+                text: 'openapi-ts',
                 items: [
-                    { text: 'Introduction', link: '/introduction' },
-                    { text: 'Quick Start', link: '/quick-start' },
-                    { text: 'Installation', link: '/installation' },
+                    { text: 'Get Started', link: '/get-started' },
                     { text: 'Configuration', link: '/configuration' },
                     { text: 'Interceptors', link: '/interceptors' },
                     { text: 'Migrating', link: '/migrating' },

docs/.vitepress/config/shared.ts

@@ -2,17 +2,23 @@ import { defineConfig } from 'vitepress';
 
 export default defineConfig({
     title: 'OpenAPI TypeScript',
-    lastUpdated: true,
+    lastUpdated: false,
     sitemap: {
         hostname: 'https://heyapi.vercel.app',
     },
     head: [
         ['link', { rel: 'icon', type: 'image/png', href: '/logo.png' }],
+        ['meta', { property: 'og:type', content: 'website' }],
+        ['meta', { property: 'og:locale', content: 'en' }],
+        ['meta', { property: 'og:title', content: 'Turn your OpenAPI specification into a beautiful TypeScript client' }],
+        ['meta', { property: 'og:site_name', content: 'OpenAPI TypeScript' }],
+        ['meta', { property: 'og:image', content: '/logo.png' }],
+        ['meta', { property: 'og:url', content: 'https://heyapi.vercel.app' }],
     ],
     themeConfig: {
         logo: '/logo.png',
         socialLinks: [
-            { icon: 'npm', link: 'https://www.npmjs.com/package/@hey-api/openapi-ts' },
+            { icon: 'npm', link: 'https://npmjs.com/package/@hey-api/openapi-ts' },
             { icon: 'github', link: 'https://github.com/hey-api/openapi-ts' },
         ],
         search: {

docs/configuration.md

@@ -5,53 +5,76 @@ description: Configure openapi-ts.
 
 # Configuration
 
-`openapi-ts` supports loading configuration from a file inside your project root directory. Your configuration can be in many formats (as supported by [c12](https://github.com/unjs/c12)). Here are some example configs:
+`openapi-ts` supports loading configuration from any file inside your project root directory supported by [jiti loader](https://github.com/unjs/c12?tab=readme-ov-file#-features). Below are the most common file formats.
 
-`openapi-ts.config.ts`
-
-```ts
+::: code-group
+```js [openapi-ts.config.ts]
 import { defineConfig } from '@hey-api/openapi-ts'
 
 export default defineConfig({
   input: 'path/to/openapi.json',
   output: 'src/client',
 })
 ```
-
-`openapi-ts.config.cjs`
-
-```js
+```js [openapi-ts.config.cjs]
 /** @type {import('@hey-api/openapi-ts').UserConfig} */
 module.exports = {
   input: 'path/to/openapi.json',
   output: 'src/client',
 }
 ```
-
-`openapi-ts.config.mjs`
-
-```js
+```js [openapi-ts.config.mjs]
 /** @type {import('@hey-api/openapi-ts').UserConfig} */
 export default {
   input: 'path/to/openapi.json',
   output: 'src/client',
 }
 ```
+:::
 
 Alternatively, you can use `openapi-ts.config.js` and configure the export statement depending on your project setup.
 
 ## Clients
 
 By default, `openapi-ts` will try to guess your client based on your project dependencies. If we don't get it right, you can specify the desired client
 
-```js
-/** @type {import('@hey-api/openapi-ts').UserConfig} */
+::: code-group
+```js{2} [fetch]
 export default {
   client: 'fetch',
   input: 'path/to/openapi.json',
   output: 'src/client',
 }
 ```
+```js{2} [axios]
+export default {
+  client: 'axios',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+}
+```
+```js{2} [angular]
+export default {
+  client: 'angular',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+}
+```
+```js{2} [node]
+export default {
+  client: 'node',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+}
+```
+```js{2} [xhr]
+export default {
+  client: 'xhr',
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+}
+```
+:::
 
 We support these clients:
 
@@ -64,16 +87,15 @@ We also support the legacy Node.js and XHR clients:
 - [node](https://nodejs.org/) (using [node-fetch](https://www.npmjs.com/package/node-fetch))
 - [xhr](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest)
 
-::: info
+::: tip
 You might not need a `node` client. Fetch API is [experimental](https://nodejs.org/docs/latest-v18.x/api/globals.html#fetch) in Node.js v18 and [stable](https://nodejs.org/docs/latest-v21.x/api/globals.html#fetch) in Node.js v21. We recommend upgrading to the latest Node.js version.
 :::
 
 ## Formatting
 
 By default, `openapi-ts` will automatically format your client according to your project configuration. To disable automatic formatting, set `format` to false
 
-```js
-/** @type {import('@hey-api/openapi-ts').UserConfig} */
+```js{2}
 export default {
   format: false,
   input: 'path/to/openapi.json',
@@ -87,8 +109,7 @@ You can also prevent your client from being processed by formatters by adding yo
 
 For performance reasons, `openapi-ts` does not automatically lint your client. To enable this feature, set `lint` to true
 
-```js
-/** @type {import('@hey-api/openapi-ts').UserConfig} */
+```js{3}
 export default {
   input: 'path/to/openapi.json',
   lint: true,
@@ -102,8 +123,7 @@ You can also prevent your client from being processed by linters by adding your
 
 If you need to iterate through possible field values without manually typing arrays, you can export enums with
 
-```js
-/** @type {import('@hey-api/openapi-ts').UserConfig} */
+```js{2}
 export default {
   enums: 'javascript',
   input: 'path/to/openapi.json',
@@ -122,8 +142,7 @@ export const FooEnum = {
 
 We discourage generating [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) because they are not standard JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh). If you really need TypeScript enums, you can export them with
 
-```js
-/** @type {import('@hey-api/openapi-ts').UserConfig} */
+```js{2}
 export default {
   enums: 'typescript',
   input: 'path/to/openapi.json',

docs/get-started.md

@@ -0,0 +1,67 @@
+---
+title: Get Started
+description: Get started with @hey-api/openapi-ts.
+---
+
+# Get Started
+
+`openapi-ts` started as a fork of [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen). We created it after the original project became [unmaintained](https://github.com/ferdikoomen/openapi-typescript-codegen/issues/1276#issuecomment-1302392146) to add support for OpenAPI v3.1. We plan to resolve the most pressing issues in the original project – open an issue if you'd like to prioritise your use case!
+
+## Features
+
+- Generate TypeScript clients from OpenAPI v2.0, v3.0, and v3.1 specifications
+- Support JSON or YAML input files
+- Handle external references using [JSON Schema $Ref Parser](https://github.com/APIDevTools/json-schema-ref-parser/)
+- Generate Fetch, Node-Fetch, Axios, Angular, or XHR HTTP clients
+- Can be used with CLI, Node.js, or npx
+- Abortable requests through cancellable promise pattern
+
+## Quick Start
+
+The fastest way to use `openapi-ts` is via npx
+
+```sh
+npx @hey-api/openapi-ts -i path/to/openapi.json -o src/client
+```
+
+Congratulations on creating your first client! 🎉
+
+## Installation
+
+::: code-group
+```sh [npm]
+npm install @hey-api/openapi-ts --save-dev
+```
+```sh [pnpm]
+pnpm add @hey-api/openapi-ts -D
+```
+```sh [yarn]
+yarn add @hey-api/openapi-ts -D
+```
+```sh [bun]
+bun add @hey-api/openapi-ts -D
+```
+:::
+
+If you want to use `openapi-ts` with CLI, add a script to your `package.json` file
+
+```json
+"scripts": {
+  "openapi-ts": "openapi-ts"
+}
+```
+
+You can also generate your client programmatically by importing `openapi-ts` in a `.ts` file.
+
+```ts
+import { createClient } from '@hey-api/openapi-ts'
+
+createClient({
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+})
+```
+
+::: warning
+You need to be running Node.js v18 or newer
+:::

docs/index.md

@@ -2,12 +2,12 @@
 layout: home
 
 hero:
-  name: "OpenAPI TypeScript"
-  tagline: "Turn your OpenAPI specification into a beautiful TypeScript client"
+  name: OpenAPI TypeScript
+  tagline: Turn your OpenAPI specification into a beautiful TypeScript client
   actions:
     - theme: brand
       text: Get Started
-      link: /introduction
+      link: /get-started
     - theme: alt
       text: View on GitHub
       link: https://github.com/hey-api/openapi-ts
@@ -16,11 +16,39 @@ hero:
     alt: logo
 
 features:
-  - title: Full Support
-    details: Generate TypeScript clients from OpenAPI v2.0, v3.0, and v3.1 specifications.
-  - title: Local or External
-    details: Support for JSON and YAML input files, or pass a remote URL to your specification.
-  - title: Clients
-    details: Generate a Fetch, Node-Fetch, Axios, Angular, or XHR HTTP client.
+  - icon: ✍️
+    title: OpenAPI Schema
+    details: You provide your OpenAPI specification. We take care of the rest. OpenAPI v2.0, v3.0, and v3.1 supported.
+  - icon: 🤖
+    title: TypeScript Interfaces
+    details: Generate types for your API data. Ensure code correctness. No manual maintenance required.
+  - icon: 🦴
+    title: Data Fetching
+    details: Let us fetch that for you. We support fetch, axios, angular, and even node or xhr clients.
 ---
 
+<style>
+:root {
+  --c-gradient-start: #91d6d5;
+  --vp-c-brand-1: #225e72;
+  --vp-c-brand-2: #55979e;
+  --vp-c-brand-3: #67abac;
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, var(--vp-c-brand-3) 30%, var(--c-gradient-start));
+
+  --vp-home-hero-image-background-image: linear-gradient(-45deg, var(--vp-c-brand-3) 50%, var(--c-gradient-start) 50%);
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+</style>