diff --git a/.editorconfig b/.editorconfig index 90e3ce9f3..19d2c846e 100755 --- a/.editorconfig +++ b/.editorconfig @@ -11,5 +11,8 @@ indent_size = 4 [*.hbs] indent_style = tab +[*.md] +indent_size = 2 + [*.yml] indent_size = 2 diff --git a/README.md b/README.md index 85cefea68..0e865c720 100644 --- a/README.md +++ b/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 diff --git a/docs/.vitepress/config/en.ts b/docs/.vitepress/config/en.ts index 1d8355924..9756c8b3f 100644 --- a/docs/.vitepress/config/en.ts +++ b/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' }, diff --git a/docs/.vitepress/config/shared.ts b/docs/.vitepress/config/shared.ts index c92c4d195..f162c276f 100644 --- a/docs/.vitepress/config/shared.ts +++ b/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: { diff --git a/docs/configuration.md b/docs/configuration.md index b8d33d555..41ee5d35b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -5,11 +5,10 @@ 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({ @@ -17,26 +16,21 @@ export default defineConfig({ 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. @@ -44,14 +38,43 @@ Alternatively, you can use `openapi-ts.config.js` and configure the export state 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,7 +87,7 @@ 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. ::: @@ -72,8 +95,7 @@ You might not need a `node` client. Fetch API is [experimental](https://nodejs.o 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', diff --git a/docs/get-started.md b/docs/get-started.md new file mode 100644 index 000000000..d413ed9c4 --- /dev/null +++ b/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 +::: diff --git a/docs/index.md b/docs/index.md index cba100f1d..02bb0e6db 100644 --- a/docs/index.md +++ b/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. --- + diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index a71141846..000000000 --- a/docs/installation.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Installation -description: Installing @hey-api/openapi-ts. ---- - -# 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 -::: diff --git a/docs/interceptors.md b/docs/interceptors.md index c74524e4e..26d9a2d80 100644 --- a/docs/interceptors.md +++ b/docs/interceptors.md @@ -7,23 +7,41 @@ description: Understanding interceptors. Interceptors (middleware) can be used to modify requests before they're sent or responses before they're returned to the rest of your application. Below is an example request interceptor -```ts +::: code-group +```ts [use] OpenAPI.interceptors.request.use((request) => { doSomethingWithRequest(request) return request // <-- must return request }) ``` +```ts [eject] +OpenAPI.interceptors.request.eject((request) => { + doSomethingWithRequest(request) + return request // <-- must return request +}) +``` +::: and an example response interceptor -```ts +::: code-group +```ts [use] OpenAPI.interceptors.response.use(async (response) => { await doSomethingWithResponse(response) // async return response // <-- must return response }) ``` +```ts [eject] +OpenAPI.interceptors.response.eject(async (response) => { + await doSomethingWithResponse(response) // async + return response // <-- must return response +}) +``` +::: -If you need to remove an interceptor, pass the same function to `OpenAPI.interceptors.request.eject()` or `OpenAPI.interceptors.response.eject()`. +::: tip +To eject, you must provide the same function that was passed to `use()`. +::: ::: warning Angular client does not currently support request interceptors. diff --git a/docs/introduction.md b/docs/introduction.md deleted file mode 100644 index 5d727a6c3..000000000 --- a/docs/introduction.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Introduction -description: Get started using @hey-api/openapi-ts. ---- - -# Introduction - -`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! diff --git a/docs/migrating.md b/docs/migrating.md index 63b604106..950c504da 100644 --- a/docs/migrating.md +++ b/docs/migrating.md @@ -7,7 +7,7 @@ description: Migrating to @hey-api/openapi-ts. While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. -### v0.27.38 +## v0.27.38 ### `useOptions: true` diff --git a/docs/quick-start.md b/docs/quick-start.md deleted file mode 100644 index d6349808d..000000000 --- a/docs/quick-start.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Quick Start -description: Get started using @hey-api/openapi-ts. ---- - -# 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! 🎉