Merge pull request #476 from hey-api/docs/examples

docs: add examples

.changeset/ninety-hairs-own.md

@@ -0,0 +1,5 @@
+---
+"@hey-api/docs": patch
+---
+
+docs: add examples

README.md

@@ -1,21 +1,35 @@
 <div align="center">
-    <img width="150" height="150" src="https://heyapi.vercel.app/logo.png" alt="Logo">
-    <h1 align="center"><b>OpenAPI Typescript</b></h1>
-    <p align="center">✨ Turn your OpenAPI specification into a beautiful TypeScript client.</p>
+  <img width="150" height="150" src="https://heyapi.vercel.app/logo.png" alt="Logo">
+  <h1 align="center"><b>OpenAPI Typescript</b></h1>
+  <p align="center">✨ Turn your OpenAPI specification into a beautiful TypeScript client.</p>
 </div>
 
-## GitHub Integration (coming soon)
+Generate TypeScript interfaces, REST clients, and JSON Schemas from OpenAPI specifications.
 
-Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.vercel.app/openapi-ts/integrations.html).
+[Live demo](https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fservices.gen.ts,src%2Fclient%2Ftypes.gen.ts)
 
-## Migrating from OpenAPI Typescript Codegen?
+## Features
 
-Please read our [migration guide](https://heyapi.vercel.app/openapi-ts/migrating.html#openapi-typescript-codegen).
+- works with CLI, Node.js, or npx
+- supports OpenAPI 2.0, 3.0, and 3.1 specifications
+- supports both JSON and YAML input files
+- supports external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
+- generates TypeScript interfaces, REST clients, and JSON Schemas
+- Fetch API, Axios, Angular, Node.js, and XHR clients available
+- abortable requests through cancellable promise pattern
 
 ## Documentation
 
 Please visit our [website](https://heyapi.vercel.app/) for documentation, guides, migrating, and more.
 
+## GitHub Integration (coming soon)
+
+Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.vercel.app/openapi-ts/integrations.html).
+
+## Migrating from OpenAPI Typescript Codegen?
+
+Please read our [migration guide](https://heyapi.vercel.app/openapi-ts/migrating.html#openapi-typescript-codegen).
+
 ## Contributing
 
 Want to get involved? Please refer to the [contributing guide](https://heyapi.vercel.app/contributing.html).

docs/.vitepress/config/shared.ts

@@ -21,8 +21,11 @@ export default defineConfig({
       {},
       'window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };',
     ],
-    ['script', { defer: '', src: '/_vercel/insights/script.js' }],
-  ],
+    process.env.NODE_ENV === 'production' && [
+      'script',
+      { defer: '', src: '/_vercel/insights/script.js' },
+    ],
+  ].filter(Boolean),
   lastUpdated: false,
   sitemap: {
     hostname: 'https://heyapi.vercel.app',

docs/.vitepress/theme/custom.css

@@ -25,3 +25,24 @@ html.dark {
   text-transform: lowercase;
   top: -1em;
 }
+
+iframe {
+  background-color: var(--vp-sidebar-bg-color);
+  border: none;
+  margin: 0;
+}
+
+.buttonLink {
+  color: var(--vp-c-brand-1);
+  font-size: 16px;
+  font-weight: 500;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  transition:
+    color 0.25s,
+    opacity 0.25s;
+}
+
+.buttonLink:hover {
+  color: var(--vp-c-brand-2);
+}

docs/embed.ts

@@ -0,0 +1,19 @@
+import sdk from '@stackblitz/sdk';
+
+export const embedProject = (projectId: string) => async (event: Event) => {
+  const container = document.createElement('div');
+
+  if (event.target) {
+    const node = event.target as HTMLElement;
+    node.replaceWith(container);
+  }
+
+  if (projectId === 'hey-api-example') {
+    return await sdk.embedProjectId(container, projectId, {
+      height: 700,
+      openFile:
+        'openapi-ts.config.ts,src/client/schemas.gen.ts,src/client/services.gen.ts,src/client/types.gen.ts',
+      view: 'editor',
+    });
+  }
+};

docs/index.md

@@ -9,8 +9,8 @@ hero:
       text: Get Started
       link: /openapi-ts/get-started
     - theme: alt
-      text: View on GitHub
-      link: https://github.com/hey-api/openapi-ts
+      text: View Demo
+      link: https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fservices.gen.ts,src%2Fclient%2Ftypes.gen.ts
   image:
     src: /logo.png
     alt: logo
@@ -38,7 +38,7 @@ features:
 
 ### Migrating from OpenAPI Typescript Codegen?
 
-Please read our [migration guide](/openapi-ts/migrating#openapi-typescript-codegen).
+Read our [migration guide](/openapi-ts/migrating#openapi-typescript-codegen).
 
 <style>
 :root {

docs/openapi-ts/clients.md

@@ -8,3 +8,7 @@ description: REST clients for your stack. Compatible with all our features.
 We all send HTTP requests in a slightly different way. Hey API doesn't force you to use any specific technology. What we do, however, is support your choice with great clients. All seamlessly integrated with our other features.
 
 [Next.js](https://nextjs.org/), [Axios](https://axios-http.com/), and [Fetch API](https://developer.mozilla.org/docs/Web/API/Fetch_API) coming soon.
+
+## Examples
+
+You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples).

docs/openapi-ts/configuration.md

@@ -239,3 +239,7 @@ export default {
 ## Config API
 
 You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/types/config.ts) interface.
+
+## Examples
+
+You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples).

docs/openapi-ts/get-started.md

@@ -3,18 +3,26 @@ title: Get Started
 description: Get started with @hey-api/openapi-ts.
 ---
 
+<script setup>
+import { embedProject } from '../embed'
+</script>
+
 # Get Started
 
-`openapi-ts` allows you to create TypeScript interfaces, REST clients, and JSON Schemas from an OpenAPI specification.
+Generate TypeScript interfaces, REST clients, and JSON Schemas from OpenAPI specifications.
+
+<button class="buttonLink" @click="(event) => embedProject('hey-api-example')(event)">
+Live demo
+</button>
 
 ## Features
 
-- use with CLI, Node.js, or npx
-- export TypeScript interfaces from OpenAPI v2.0, v3.0, and v3.1 specifications
-- support JSON or YAML input files
-- support external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
-- create fetch, axios, angular, node.js, or xhr REST clients
-- export JSON Schemas from OpenAPI specifications
+- works with CLI, Node.js, or npx
+- supports OpenAPI 2.0, 3.0, and 3.1 specifications
+- supports both JSON and YAML input files
+- supports external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
+- generates TypeScript interfaces, REST clients, and JSON Schemas
+- Fetch API, Axios, Angular, Node.js, and XHR clients available
 - abortable requests through cancellable promise pattern
 
 ## Quick Start
@@ -71,3 +79,7 @@ createClient({
 ::: warning
 You need to be running Node.js v18 or newer
 :::
+
+## Examples
+
+You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples).

docs/openapi-ts/interceptors.md

@@ -52,3 +52,7 @@ To eject, you must provide the same function that was passed to `use()`.
 ::: warning
 Angular client does not currently support request interceptors.
 :::
+
+## Examples
+
+You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples).

docs/package.json

@@ -9,6 +9,9 @@
     "dev": "vitepress dev",
     "preview": "vitepress preview"
   },
+  "dependencies": {
+    "@stackblitz/sdk": "1.9.0"
+  },
   "devDependencies": {
     "vitepress": "1.1.3"
   }

packages/openapi-ts/README.md

@@ -4,18 +4,24 @@
   <p align="center">✨ Turn your OpenAPI specification into a beautiful TypeScript client.</p>
 </div>
 
-`openapi-ts` allows you to create TypeScript interfaces, REST clients, and JSON Schemas from an OpenAPI specification.
+Generate TypeScript interfaces, REST clients, and JSON Schemas from OpenAPI specifications.
+
+[Live demo](https://stackblitz.com/edit/hey-api-example?file=openapi-ts.config.ts,src%2Fclient%2Fschemas.gen.ts,src%2Fclient%2Fservices.gen.ts,src%2Fclient%2Ftypes.gen.ts)
 
 ## Features
 
-- use with CLI, Node.js, or npx
-- export TypeScript interfaces from OpenAPI v2.0, v3.0, and v3.1 specifications
-- support JSON or YAML input files
-- support external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
-- create fetch, axios, angular, node.js, or xhr REST clients
-- export JSON Schemas from OpenAPI specifications
+- works with CLI, Node.js, or npx
+- supports OpenAPI 2.0, 3.0, and 3.1 specifications
+- supports both JSON and YAML input files
+- supports external references using [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/)
+- generates TypeScript interfaces, REST clients, and JSON Schemas
+- Fetch API, Axios, Angular, Node.js, and XHR clients available
 - abortable requests through cancellable promise pattern
 
+## Documentation
+
+Please visit our [website](https://heyapi.vercel.app/) for documentation, guides, migrating, and more.
+
 ## GitHub Integration (coming soon)
 
 Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.vercel.app/openapi-ts/integrations.html).
@@ -24,10 +30,6 @@ Automatically update your code when the APIs it depends on change. [Find out mor
 
 Please read our [migration guide](https://heyapi.vercel.app/openapi-ts/migrating.html#openapi-typescript-codegen).
 
-## Documentation
-
-Please visit our [website](https://heyapi.vercel.app/) for documentation, guides, migrating, and more.
-
 ## Contributing
 
 Want to get involved? Please refer to the [contributing guide](https://heyapi.vercel.app/contributing.html).