docs: add integrations

.changeset/giant-mice-hug.md

@@ -0,0 +1,5 @@
+---
+"openapi-ts-docs": minor
+---
+
+docs: add integrations

README.md

@@ -4,6 +4,10 @@
     <p align="center">✨ Turn your OpenAPI specification into a beautiful TypeScript client.</p>
 </div>
 
+## 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).

docs/.vitepress/config/en.ts

@@ -11,13 +11,14 @@ export default defineConfig({
                     { text: 'Get Started', link: '/openapi-ts/get-started' },
                     { text: 'Configuration', link: '/openapi-ts/configuration' },
                     { text: 'Interceptors', link: '/openapi-ts/interceptors' },
+                    { text: 'Integrations <span class="soon">soon</span>', link: '/openapi-ts/integrations' },
                     { text: 'Migrating', link: '/openapi-ts/migrating' },
                 ],
             },
             {
                 text: '@hey-api',
                 items: [
-                    { text: 'About', link: '/about' },
+                    { text: 'Philosophy', link: '/about' },
                     { text: 'Contributing', link: '/contributing' },
                 ],
             },

docs/.vitepress/config/index.ts

@@ -1,22 +1,11 @@
+import { defineConfig } from 'vitepress';
+
 import en from './en';
 import shared from './shared';
 
-import { withMermaid } from 'vitepress-plugin-mermaid';
-
-export default withMermaid({
+export default defineConfig({
     ...shared,
     locales: {
         root: { label: 'English', ...en },
     },
-    /**
-     * mermaid fix
-     * {@link https://github.com/mermaid-js/mermaid/issues/4320}
-     */
-    vite: {
-        optimizeDeps: {
-            include: [
-                'mermaid'
-            ]
-        }
-    }
 });

docs/.vitepress/theme/custom.css

@@ -14,3 +14,14 @@ html.dark {
     --vp-c-brand-2: #b3cde4;
     --vp-c-brand-3: #537692;
 }
+
+.soon {
+    background-color: var(--vp-button-brand-bg);
+    border-radius: 1em;
+    color: var(--vp-button-brand-text);
+    font-size: .6em;
+    padding: .2em .4em;
+    position: relative;
+    text-transform: lowercase;
+    top: -1em;
+}

docs/about.md

@@ -1,5 +1,5 @@
 ---
-title: About
+title: Philosophy
 description: Hello from Hey API.
 ---
 
@@ -13,18 +13,8 @@ Typically, developers of such applications want to:
 - send and fetch this data from server in a typesafe way
 - build further abstractions on top of this data
 
-```mermaid
-flowchart LR
-  id1(Application) --> id2(API types) --> id3(API request wrapper) --> id4(REST endpoint)
-```
-
 Doing any of these steps manually quickly becomes a huge time sink as your project grows and APIs evolve. Ideally, you want to spend most time on your application. Hey API allows you to do just that.
 
-```mermaid
-flowchart LR
-  id1(Application) --> id2(Hey API) --> id3(REST endpoint)
-```
-
 We're constantly learning about the ways in which you use our tools. If you have any feedback, please [email us](mailto:[email protected]), [open an issue](https://github.com/hey-api/openapi-ts/issues), or [join a discussion](https://github.com/hey-api/openapi-ts/discussions).
 
 ## Team

docs/index.md

@@ -16,16 +16,19 @@ hero:
     alt: logo
 
 features:
-  - icon: ✍️
+  - 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>
+    details: Automatically update your code when the APIs it depends on change. Works with any codegen.
+  - icon: <svg class="icon-openapi" width="24" height="24" fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 30 32"><path d="M8.96 18.397H.515l.005.123.014.238.007.102.022.275.006.061.033.304.003.03.043.327c.098.677.243 1.343.437 1.999l.003.008.1.326.006.018.093.276.025.07.087.24.04.107.078.2.06.149.065.154.086.188.05.114.105.225.035.072.126.256.02.039.154.293.033.057 7.235-4.366a5.754 5.754 0 0 1-.528-1.885ZM.914 22.27l.002.007.273-.085-.275.078ZM11.034 22.275l-5.97 5.967.092.085.255.227.203.172.055.045.232.187.03.024.255.196a.066.066 0 0 1 .01.007l1.113.752.04.024.219.13.134.076.128.072.232.126.032.017.658.32 3.213-7.805a5.719 5.719 0 0 1-.934-.623l.003.001ZM10.415 21.683l-.186-.219-.154-.199-.165-.233-.154-.241-7.22 4.349.371.584.03.044.002.003.388.547.009.011.008.011.176.229.21.261.045.055.173.203.076.087.15.171.084.092.039.042.114.12.046.047.2.204 5.956-5.956-.195-.209-.003-.003ZM18.31 22.272l-.2.154.016.025 4.342 7.209.594-.41c.42-.31.827-.645 1.22-1.007l-5.949-5.947-.023-.024ZM21.92 30.003l.01-.006-.01.006Zm-.005.003ZM21.929 29.994l.057-.028-.001-.002-.056.033v-.003Zm-.01.009-.002.001.002-.001ZM21.916 30.006l-.011-.018.01.018Zm.004-.003.01-.005-.01.005Z" fill="#fff"></path><path d="m21.837 29.719-4.2-6.97-.25.139-.256.128a5.756 5.756 0 0 1-4.106.319l-.27-.095-.27-.095-3.207 7.788.024.009.024.009.007.003.615.235a14.262 14.262 0 0 0 3.007.708l.349.038.056.005.28.023.095.006.245.014.15.006.195.007.348.004c.788 0 1.575-.066 2.352-.196l.04-.006.246-.045.143-.027.145-.03.24-.053.044-.01a14.241 14.241 0 0 0 3.398-1.267l.209-.115.424-.238-.007-.02.01.018.014-.008.056-.034-.15-.25Zm-10.8-16.335.2-.155-.015-.024-4.343-7.206-.595.41c-.42.31-.827.645-1.218 1.006l5.948 5.945.024.024ZM4.654 7.808l-.395.413c-.44.476-.841.971-1.203 1.491l-.052.075-.121.178-.123.188-.045.068a14.135 14.135 0 0 0-2.2 7.035l-.007.286-.005.285h8.424l.013-.285.016-.286a5.716 5.716 0 0 1 1.27-3.068c.058-.073.128-.142.192-.212.065-.07.124-.144.192-.212L4.654 7.808Zm17.38-2.09L22 5.695l-.224-.132-.13-.075-.132-.073-.228-.123-.036-.019a14.74 14.74 0 0 0-1.52-.686l-.04-.015-.342-.124a14.216 14.216 0 0 0-2.839-.673l-.118-.016-.119-.013-.228-.025-.064-.006-.273-.023-.342-.02-.124-.006v8.444c.433.045.862.138 1.279.279l6.216-6.211a13.96 13.96 0 0 0-.703-.461h.002ZM7.363 5.692l.147.244-.147-.244Zm0 0L7.36 5.69l.004.002Z" fill="#fff"></path><path d="m14.388 3.664-.285.005a14.24 14.24 0 0 0-1.78.184l-.04.007-.247.044-.143.027-.145.03-.24.053-.043.01a14.252 14.252 0 0 0-3.4 1.268l-.705.398v.001l4.349 7.219.25-.14a5.727 5.727 0 0 1 2.141-.657l.285-.022s.19-.01.286-.01V3.658c-.095 0-.19.003-.285.005h.002ZM28.827 17.131l-.014-.227-.007-.113-.022-.267-.006-.07-.032-.297-.002-.024-.002-.012-.043-.32-.001-.01a14.164 14.164 0 0 0-.436-1.992l-.003-.013-.094-.304-.013-.04-.091-.272-.026-.074-.086-.235-.043-.111-.075-.194-.063-.153-.063-.15-.083-.191-.049-.108-.107-.228-.033-.069-.128-.259-.018-.035-.149-.286c-.002-.003-.003-.007-.006-.01a14.217 14.217 0 0 0-.806-1.308l-6.217 6.218c.14.415.233.844.278 1.279h8.444l-.004-.125ZM20.42 17.828l-.013.285-.016.286a5.709 5.709 0 0 1-1.27 3.068c-.057.073-.128.142-.192.212s-.123.144-.191.212l5.956 5.956c.067-.068.13-.138.197-.206l.197-.207c.44-.477.843-.977 1.206-1.496l.043-.06.13-.193.113-.173.057-.084a14.13 14.13 0 0 0 2.196-7.03l.007-.285.005-.286H20.42Z" fill="#fff"></path></svg>
     title: OpenAPI Schema
-    details: You provide OpenAPI specification. We take care of the rest. OpenAPI v2.0, v3.0, and v3.1 supported.
-  - icon: 🤖
+    details: You provide OpenAPI schema. We take care of the rest. OpenAPI v2.0, v3.0, and v3.1 supported.
+  - 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.
   - icon: 🦴
     title: Data Fetching
     details: Typesafe data with our REST clients. Fetch, axios, angular, node, and xhr are available.
-  - icon: "{✓}"
+  - 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.
 ---
@@ -40,15 +43,29 @@ Interested in partnership or sponsoring Hey API? [Send us an email](mailto:lmenu
 
 <style>
 :root {
+  --github-mark-fill-color: #24292f;
   --vp-home-hero-name-color: transparent;
   --vp-home-hero-name-background: -webkit-linear-gradient(120deg, var(--c-gradient-start) 30%, var(--vp-c-brand-3));
 }
 
 html.dark {
+  --github-mark-fill-color: #fff;
   --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(144px);
 }
 
+.icon-github path {
+  fill: var(--github-mark-fill-color);
+}
+
+.icon-json-schema path {
+  fill: var(--github-mark-fill-color);
+}
+
+.icon-openapi path {
+  fill: var(--github-mark-fill-color);
+}
+
 @media (min-width: 640px) {
   html.dark {
     --vp-home-hero-image-filter: blur(156px);

docs/openapi-ts/integrations.md

@@ -0,0 +1,22 @@
+---
+title: Integrations
+description: Automate your client generation.
+---
+
+# Integrations <span class="soon">Soon</span>
+
+Integrations allow you to automate your client generation workflow. We suggest using them with `openapi-ts`, but you can use any codegen.
+
+<br/>
+
+::: tip
+Integrations are in beta. If you'd like to be one of the first users, [send us an email](mailto:[email protected]).
+:::
+
+## Upload OpenAPI Spec
+
+More information will be provided as we finalize the tooling.
+
+## Configure Clients
+
+More information will be provided as we finalize the tooling.

docs/openapi-ts/migrating.md

@@ -52,15 +52,6 @@ This config option is deprecated and will be removed.
 
 ## v0.39.0
 
-### Prefer `unknown` over `any`
-
-Types that cannot be determined will now be generated as `unknown` instead of `any`.
-
-```js
-200: any // [!code --]
-200: unknown // [!code ++]
-```
-
 ### Single `enums.gen.ts` file
 
 Enums are now exported from a separate file. If you use imports from `models.ts`, you can change them to `enums.gen.ts`.
@@ -109,6 +100,14 @@ import { $Schema } from 'client/schemas.gen' // [!code ++]
 import { DefaultService } from 'client/services.gen' // [!code ++]
 ```
 
+### Prefer `unknown`
+
+Types that cannot be determined will now be generated as `unknown` instead of `any`. To dismiss any errors, you can cast your variables back to `any`, but we recommend updating your code to work with `unknown` types.
+
+```js
+const foo = bar as any
+```
+
 ## v0.38.0
 
 ### Renamed `write`

docs/package.json

@@ -10,8 +10,6 @@
         "preview": "vitepress preview"
     },
     "devDependencies": {
-        "mermaid": "10.9.0",
-        "vitepress": "1.1.0",
-        "vitepress-plugin-mermaid": "2.0.16"
+        "vitepress": "1.1.0"
     }
 }