Merge branch 'main' of https://github.com/nicolas-chaulet/openapi-typ…

…escript-codegen into fix/client-beta-2
hey-api · Jun 9, 2024 · a042122 · a042122
2 parents 28fd8dd + 8af0fdb
commit a042122
Show file tree

Hide file tree

Showing 104 changed files with 6,141 additions and 1,637 deletions.
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -1,11 +1,16 @@
 {
-    "$schema": "https://unpkg.com/@changesets/config@2.3.1/schema.json",
-    "changelog": ["@svitejs/changesets-changelog-github-compact", { "repo": "hey-api/openapi-ts" }],
-    "commit": false,
-    "fixed": [],
-    "linked": [],
-    "access": "public",
-    "baseBranch": "main",
-    "updateInternalDependencies": "patch",
-    "ignore": []
+  "$schema": "https://unpkg.com/@changesets/config@2.3.1/schema.json",
+  "access": "public",
+  "baseBranch": "main",
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "hey-api/openapi-ts"
+    }
+  ],
+  "commit": false,
+  "fixed": [],
+  "ignore": [],
+  "linked": [],
+  "updateInternalDependencies": "patch"
 }
diff --git a/.changeset/rich-grapes-matter.md b/.changeset/rich-grapes-matter.md
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ Generate TypeScript interfaces, REST clients, and JSON Schemas from OpenAPI spec
 
 ## Features
 
-- works with CLI, Node.js, or npx
+- works with CLI, Node.js 18+, or npx
 - supports OpenAPI 2.0, 3.0, and 3.1 specifications
 - supports both JSON and YAML input files
 - generates TypeScript interfaces, REST clients, and JSON Schemas

diff --git a/docs/.vitepress/config/en.ts b/docs/.vitepress/config/en.ts
@@ -10,8 +10,20 @@ export default defineConfig({
         items: [
           { link: '/openapi-ts/get-started', text: 'Get Started' },
           { link: '/openapi-ts/configuration', text: 'Configuration' },
+        ],
+        text: '@hey-api/openapi-ts',
+      },
+      {
+        items: [
+          { link: '/openapi-ts/output', text: 'Output' },
           { link: '/openapi-ts/clients', text: 'Clients' },
           { link: '/openapi-ts/interceptors', text: 'Interceptors' },
+          { link: '/openapi-ts/migrating', text: 'Migrating' },
+        ],
+        text: 'Guides and Concepts',
+      },
+      {
+        items: [
           {
             link: '/openapi-ts/integrations',
             text: 'Integrations <span class="soon">soon</span>',
@@ -20,9 +32,8 @@ export default defineConfig({
             link: '/openapi-ts/tanstack-query',
             text: 'TanStack Query <span class="soon">soon</span>',
           },
-          { link: '/openapi-ts/migrating', text: 'Migrating' },
         ],
-        text: 'openapi-ts',
+        text: 'Plugins',
       },
       {
         items: [

diff --git a/docs/.vitepress/config/shared.ts b/docs/.vitepress/config/shared.ts
@@ -1,4 +1,4 @@
-import { defineConfig } from 'vitepress';
+import { defineConfig, type HeadConfig } from 'vitepress';
 
 export default defineConfig({
   head: [
@@ -25,7 +25,7 @@ export default defineConfig({
       'script',
       { defer: '', src: '/_vercel/insights/script.js' },
     ],
-  ].filter(Boolean),
+  ].filter(Boolean) as HeadConfig[],
   lastUpdated: false,
   sitemap: {
     hostname: 'https://heyapi.vercel.app',

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @hey-api/docs
 
+## 0.5.7
+
+### Patch Changes
+
+- [#632](https://github.com/hey-api/openapi-ts/pull/632) [`9c16bc7`](https://github.com/hey-api/openapi-ts/commit/9c16bc71cde48c0cb700b7e720a9e2ad56ec5f02) Thanks [@mrlubos](https://github.com/mrlubos)! - docs: add output page
+
 ## 0.5.6
 
 ### Patch Changes

diff --git a/docs/about.md b/docs/about.md
@@ -3,9 +3,9 @@ title: Philosophy
 description: Hello from Hey API.
 ---
 
-# About Hey API
+# About
 
-Hey API's objective is to provide a set of TypeScript tools to manage API interactions. Whether you're building a front-end application, API-to-API service, or micro-frontends, we want Hey API to be your go-to resource.
+Hey API's objective is to provide a suite of TypeScript tools to manage API interactions. Whether you're building a front-end application, API-to-API service, or micro-frontends, we want Hey API to be your go-to resource.
 
 Typically, developers of such applications want to:
 

diff --git a/docs/embed.ts b/docs/embed.ts
@@ -1,5 +1,7 @@
 import sdk from '@stackblitz/sdk';
 
+// https://api.npmjs.org/versions/@hey-api%2Fopenapi-ts/last-week
+
 export const embedProject = (projectId: string) => async (event: Event) => {
   const container = document.createElement('div');
 

diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,3 @@
+## Examples
+
+You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples).
diff --git a/docs/index.md b/docs/index.md
@@ -24,19 +24,17 @@ features:
   - icon: <svg fill="none" height="24" viewBox="0 0 128 128" width="24" xmlns="http://www.w3.org/2000/svg"><rect fill="#3178c6" height="128" rx="6" width="128"/><path clip-rule="evenodd" d="m74.2622 99.468v14.026c2.2724 1.168 4.9598 2.045 8.0625 2.629 3.1027.585 6.3728.877 9.8105.877 3.3503 0 6.533-.321 9.5478-.964 3.016-.643 5.659-1.702 7.932-3.178 2.272-1.476 4.071-3.404 5.397-5.786 1.325-2.381 1.988-5.325 1.988-8.8313 0-2.5421-.379-4.7701-1.136-6.6841-.758-1.9139-1.85-3.6159-3.278-5.1062-1.427-1.4902-3.139-2.827-5.134-4.0104-1.996-1.1834-4.246-2.3011-6.752-3.353-1.8352-.7597-3.4812-1.4975-4.9378-2.2134-1.4567-.7159-2.6948-1.4464-3.7144-2.1915-1.0197-.7452-1.8063-1.5341-2.3598-2.3669-.5535-.8327-.8303-1.7751-.8303-2.827 0-.9643.2476-1.8336.7429-2.6079s1.1945-1.4391 2.0976-1.9943c.9031-.5551 2.0101-.9861 3.3211-1.2929 1.311-.3069 2.7676-.4603 4.3699-.4603 1.1658 0 2.3958.0877 3.6928.263 1.296.1753 2.6.4456 3.911.8109 1.311.3652 2.585.8254 3.824 1.3806 1.238.5552 2.381 1.198 3.43 1.9285v-13.1051c-2.127-.8182-4.45-1.4245-6.97-1.819s-5.411-.5917-8.6744-.5917c-3.3211 0-6.4674.3579-9.439 1.0738-2.9715.7159-5.5862 1.8336-7.844 3.353-2.2578 1.5195-4.0422 3.4553-5.3531 5.8075-1.311 2.3522-1.9665 5.1646-1.9665 8.4373 0 4.1785 1.2017 7.7433 3.6052 10.6945 2.4035 2.9513 6.0523 5.4496 10.9466 7.495 1.9228.7889 3.7145 1.5633 5.375 2.323 1.6606.7597 3.0954 1.5486 4.3044 2.3668s2.1628 1.7094 2.8618 2.6736c.7.9643 1.049 2.06 1.049 3.2873 0 .9062-.218 1.7462-.655 2.5202s-1.1 1.446-1.9885 2.016c-.8886.57-1.9956 1.016-3.3212 1.337-1.3255.321-2.8768.482-4.6539.482-3.0299 0-6.0305-.533-9.0021-1.6-2.9715-1.066-5.7245-2.666-8.2591-4.799zm-23.5596-34.9136h18.2974v-11.5544h-51v11.5544h18.2079v51.4456h14.4947z" fill="#fff" fill-rule="evenodd"/></svg>
     title: TypeScript Interfaces
     details: Ensure code correctness without runtime overhead. No manual maintenance required.
-    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
-    linkText: View demo
+    link: /openapi-ts/output
+    linkText: Learn more
   - icon: 🦴
     title: Data Fetching
-    details: Typesafe data with our REST clients. Fetch, axios, angular, node, and xhr are available.
-    link: /openapi-ts/configuration#clients
-    # TODO: update link after releasing clients
-    # link: /openapi-ts/clients
+    details: Typesafe data with our REST clients. Fetch, Axios, Angular, Node, and XHR are available.
+    link: /openapi-ts/clients
     linkText: See all clients
   - icon: <svg class="icon-json-schema xmlns="http://www.w3.org/2000/svg" viewBox="0 0 70.423 70.423" height="24" width="24"><g fill="#fff"><path d="M122.994 114.19c-4.329-.94-7.58-3.479-8.712-6.801-.79-2.316-.677-6.072.333-11.15.485-2.439.882-5.349.882-6.467-.001-3.718-1.712-5.736-5.1-6.017l-1.955-.162v-4.785l1.852-.251c2.702-.366 3.744-1.029 4.576-2.91.611-1.38.689-2.068.505-4.472-.119-1.562-.535-4.349-.924-6.192-.99-4.683-.949-8.485.117-10.773 1.568-3.369 5.437-5.855 9.932-6.383l1.933-.227v5.036h-1.3c-1.771 0-4.25 1.262-4.883 2.488-.608 1.176-.654 2.864-.158 5.802.783 4.644 1.047 9.099.676 11.422-.425 2.658-1.975 5.796-3.68 7.448l-1.18 1.144 1.615 1.983c1.99 2.443 2.765 4.148 3.243 7.142.378 2.369.085 7.283-.67 11.214-1.054 5.485.162 7.652 4.661 8.306l1.676.244v2.448c0 2.792.171 2.697-3.439 1.913z" style="stroke-width:.35277775" transform="translate(-104.228 -45.508)"/><path d="M152.23 112.25v-2.43l2.05-.424c2.263-.467 4.054-1.863 4.459-3.475.127-.507-.113-3.164-.534-5.903-1.372-8.93-.611-13.537 2.855-17.297l1.482-1.608-1.11-1.266c-3.98-4.53-4.67-8.552-3.154-18.37.763-4.945.764-4.993.087-6.173-.797-1.388-3.284-2.776-4.975-2.776h-1.16v-2.47c0-2.81-.058-2.773 3.246-2.072 3.965.841 6.805 2.853 8.278 5.865.846 1.728.973 2.4.95 5.01-.016 1.66-.358 4.683-.762 6.72-1.499 7.564-1.365 9.576.765 11.533.99.908 1.64 1.173 3.37 1.368l2.145.243v4.848h-1.676c-2.151.001-3.932.91-4.838 2.47-.952 1.637-.893 5.206.173 10.406.907 4.422 1.053 8.459.389 10.729-.701 2.394-3.82 5.296-6.748 6.277-1.261.423-2.968.871-3.792.996l-1.5.228z" style="stroke-width:.35277778" transform="translate(-104.228 -45.508)"/><path d="M131.742 108.266c-1.021-1.299-.873-3.537.381-5.732.928-1.624 4.809-6.948 7.61-10.44l1.132-1.41-1.802-5.226c-2.022-5.86-2.01-5.974.656-6.372l1.468-.219 1.64 3.35c.903 1.843 1.77 3.351 1.928 3.351.158 0 1.775-1.755 3.594-3.9 3.16-3.727 3.357-3.892 4.426-3.694.645.12 1.218.047 1.354-.173.318-.515 1.23.247 1.23 1.027 0 .32-.453 1.134-1.009 1.81-2.267 2.755-7.104 9.27-7.104 9.57 0 .177.975 2.454 2.167 5.059l2.166 4.736-.658.985c-.362.541-.662 1.126-.667 1.299-.005.173-.278.483-.606.69-.832.525-1.447-.115-3.99-4.153-1.164-1.848-2.231-3.365-2.372-3.37-.313-.01-3.79 5.133-6.48 9.581-2.37 3.924-1.938 3.42-3.265 3.801-.956.274-1.194.199-1.799-.57zM131.986 83.677c-2.152-3.847-6.019-9.428-7.579-10.938-.792-.767-1.44-1.575-1.44-1.796 0-.601 1.616-1.22 3.19-1.22 1.698 0 3.496 1.479 5.1 4.193.582.985 1.156 1.794 1.276 1.798.12.004.809-1.651 1.53-3.678 1.547-4.34 5.624-12.778 7.225-14.951 1.373-1.863 3.43-2.865 5.903-2.876 3.234-.013 3.243.13.205 3.297-4.636 4.832-6.764 8.81-11.252 21.037-1.246 3.396-2.39 6.48-2.542 6.852-.23.566-.498.281-1.616-1.718z" style="stroke-width:.35277775" transform="translate(-104.228 -45.508)"/></g></svg>
     title: JSON Schemas
     details: Export OpenAPI schemas as JavaScript objects. JSON Schema 2020-12 supported.
-    link: /openapi-ts/configuration#json-schemas
+    link: /openapi-ts/output#json-schemas
     linkText: Learn more
   - icon: <svg class="icon-github" width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 98 98"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#24292f"/></svg>
     title: GitHub Integration <span class="soon">Soon</span>

diff --git a/docs/openapi-ts/clients.md b/docs/openapi-ts/clients.md
@@ -27,7 +27,7 @@ We all send HTTP requests in a slightly different way. Hey API doesn't force you
 Fetch API client is currently in beta. The interface might change before it becomes stable. We encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
 :::
 
-Start by adding `@hey-api/client-fetch` into your project's dependencies.
+Start by adding `@hey-api/client-fetch` to your dependencies.
 
 ::: code-group
 
@@ -49,7 +49,7 @@ bun add @hey-api/client-fetch
 
 :::
 
-Ensure you have already [installed](/openapi-ts/get-started) and configured `@hey-api/openapi-ts`. Update your configuration to use the client package.
+Ensure you have already [configured](/openapi-ts/get-started) `@hey-api/openapi-ts`. Update your configuration to use the Fetch API client package.
 
 ```js{2}
 export default {
@@ -59,11 +59,11 @@ export default {
 }
 ```
 
-You can now run `openapi-ts` as usual to generate the new services.
+You can now run `openapi-ts` to use the new Fetch API client. 🎉
 
 ### Configuration
 
-You will most likely want to configure the global client instance used by services. You can do that with the `createClient()` method. Call it at the beginning of your program.
+You will most likely want to configure the global client instance used by services. You can do that with the `createClient()` method. Call it at the beginning of your application.
 
 ```js
 import { createClient } from '@hey-api/client-fetch';
@@ -96,10 +96,26 @@ Live demo
 
 ## Legacy Clients
 
-Before standalone client packages, clients were generated using `@hey-api/openapi-ts`. If you want to generate a legacy client that isn't published as a standalone package, you can use the `client` config option.
+Before standalone client packages, clients were generated using `@hey-api/openapi-ts`. In fact, `@hey-api/openapi-ts` still generates a legacy Fetch API client by default. You can generate other legacy clients with the `client` config option.
 
 ::: 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',
@@ -124,14 +140,27 @@ export default {
 }
 ```
 
+:::
+
 The following legacy clients are available:
 
 - [angular](https://angular.io/) (using [RxJS](https://rxjs.dev/))
+- [axios](https://axios-http.com/)
+- [fetch](https://developer.mozilla.org/docs/Web/API/Fetch_API)
 - [node](https://nodejs.org/) (using [node-fetch](https://www.npmjs.com/package/node-fetch))
 - [xhr](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest)
 
+Please be aware that legacy clients are missing some features:
+
+- no typesafe errors 🚫
+- no access to the original request and response 🚫
+- hard to configure individual requests 👎
+- inconsistent interceptors and response APIs 👎
+
 If you'd like a standalone package for your client, let us know by [opening an issue](https://github.com/hey-api/openapi-ts/issues).
 
-## Examples
+::: 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.
+:::
 
-You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples).
+<!--@include: ../examples.md-->
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		## Examples

		You can view live examples on [StackBlitz](https://stackblitz.com/orgs/github/hey-api/collections/openapi-ts-examples).