From 53f17774e9489970b2c1977f91fc8303e720681c Mon Sep 17 00:00:00 2001 From: Lubos Date: Tue, 23 Apr 2024 11:52:41 +0100 Subject: [PATCH] docs: add examples --- .changeset/ninety-hairs-own.md | 5 +++++ README.md | 28 +++++++++++++++++++++------- docs/.vitepress/config/shared.ts | 7 +++++-- docs/.vitepress/theme/custom.css | 21 +++++++++++++++++++++ docs/embed.ts | 19 +++++++++++++++++++ docs/index.md | 6 +++--- docs/openapi-ts/clients.md | 4 ++++ docs/openapi-ts/configuration.md | 4 ++++ docs/openapi-ts/get-started.md | 26 +++++++++++++++++++------- docs/openapi-ts/interceptors.md | 4 ++++ docs/package.json | 3 +++ packages/openapi-ts/README.md | 24 +++++++++++++----------- pnpm-lock.yaml | 8 ++++++++ 13 files changed, 129 insertions(+), 30 deletions(-) create mode 100644 .changeset/ninety-hairs-own.md create mode 100644 docs/embed.ts diff --git a/.changeset/ninety-hairs-own.md b/.changeset/ninety-hairs-own.md new file mode 100644 index 000000000..2b588d1e1 --- /dev/null +++ b/.changeset/ninety-hairs-own.md @@ -0,0 +1,5 @@ +--- +"@hey-api/docs": patch +--- + +docs: add examples diff --git a/README.md b/README.md index d6db0c092..7850e3479 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,35 @@
- Logo -

OpenAPI Typescript

-

✨ Turn your OpenAPI specification into a beautiful TypeScript client.

+ Logo +

OpenAPI Typescript

+

✨ Turn your OpenAPI specification into a beautiful TypeScript client.

-## 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). diff --git a/docs/.vitepress/config/shared.ts b/docs/.vitepress/config/shared.ts index 9577de68b..83e02bbec 100644 --- a/docs/.vitepress/config/shared.ts +++ b/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', diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css index 68a087612..1dc449523 100644 --- a/docs/.vitepress/theme/custom.css +++ b/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); +} diff --git a/docs/embed.ts b/docs/embed.ts new file mode 100644 index 000000000..dcc1d4c82 --- /dev/null +++ b/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', + }); + } +}; diff --git a/docs/index.md b/docs/index.md index ad8c4f0b7..3ebfc3017 100644 --- a/docs/index.md +++ b/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).