Merge pull request #1774 from hey-api/docs/platform-guide

docs: announce Hey API platform

Author: mrlubos

.changeset/good-ligers-matter.md

@@ -0,0 +1,10 @@
+---
+'@hey-api/client-axios': patch
+'@hey-api/client-fetch': patch
+'@hey-api/client-next': patch
+'@hey-api/client-nuxt': patch
+'@hey-api/openapi-ts': patch
+'@docs/openapi-ts': patch
+---
+
+docs: announce Hey API platform

README.md

@@ -36,6 +36,11 @@
 - generates TypeScript interfaces and SDKs
 - Fetch API, Axios, Nuxt, Angular, Node.js, and XHR clients available
 - plugin ecosystem to reduce third-party boilerplate
+- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
+
+## Platform
+
+Our platform for OpenAPI specifications is now available. Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations).
 
 ## Sponsors
 
@@ -47,10 +52,6 @@ Love Hey API? Become our [sponsor](https://github.com/sponsors/hey-api).
   </a>
 </p>
 
-## GitHub Integration (coming 2025)
-
-Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
-
 ## Quick Start
 
 The fastest way to use `@hey-api/openapi-ts` is via npx

docs/.vitepress/config/en.ts

@@ -210,7 +210,7 @@ export default defineConfig({
         items: [
           {
             link: '/openapi-ts/integrations',
-            text: 'GitHub <span data-soon>soon</span>',
+            text: 'GitHub',
           },
         ],
         text: 'Integrations',

docs/index.md

@@ -40,7 +40,7 @@ features:
     link: /openapi-ts/plugins
     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: Integrations <span data-soon>Soon</span>
+    title: Integrations
     details: Automatically update your code when the APIs it depends on change. Works with any codegen.
     link: /openapi-ts/integrations
     linkText: Find out more

docs/openapi-ts/get-started.md

@@ -29,6 +29,7 @@ Launch demo
 - generates TypeScript interfaces and SDKs
 - Fetch API, Axios, Nuxt, Angular, Node.js, and XHR clients available
 - plugin ecosystem to reduce third-party boilerplate
+- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
 
 ## Quick Start
 

docs/openapi-ts/integrations.md

@@ -1,19 +1,38 @@
 ---
-title: Integrations
-description: Automate your client generation.
+title: Hey API Platform
+description: Automate your client generation with our OpenAPI specifications storage.
 ---
 
-# Integrations <span data-soon>Soon</span>
+# Hey API Platform
 
 ::: warning
-GitHub integration is not publicly available yet. We are gathering feedback from beta testers to ensure the final product meets our quality standards. To express your interest in joining the beta test, please open an issue on [GitHub](https://github.com/hey-api/upload-openapi-spec/issues).
+This feature is in development! :tada: Try it out and provide feedback on [GitHub](https://github.com/orgs/hey-api/discussions/1773).
 :::
 
-Integrations allow you to automate your client generation workflow. Create dependency links between your clients and APIs, and watch the magic unfold. While we prefer to use `@hey-api/openapi-ts` for generating clients, you can use any codegen.
+You can automate your client generation with our platform thanks to reproducible builds. Create dependency links between your clients and APIs, and watch the magic unfold. It's completely language and codegen agnostic.
 
-## Upload OpenAPI Spec
+## Features
 
-First, you need to configure your API build workflow to send us OpenAPI specifications. This can be done by adding our [hey-api/upload-openapi-spec](https://github.com/marketplace/actions/upload-openapi-spec-by-hey-api) GitHub Action into your CI workflow.
+- API version history
+- real-time updates
+- reproducible builds
+- language and codegen agnostic (TypeScript/Python/Go/Java/etc codegens are welcome)
+
+## Upload Specifications
+
+Before you can generate clients, you must publish your OpenAPI specifications to Hey API.
+
+### Prerequisites
+
+1. Create a **free account** with [Hey API](https://app.heyapi.dev/).
+1. Create a new **organization** and **project** for your API provider. We recommend your naming matches your GitHub structure as it will be referenced by API clients. For example, we are using **hey-api/backend** for the platform.
+1. Inside your project, go to _Integrations_ > _APIs_ and generate an **API key**. Keep this value secret, it will be used to upload files.
+
+### Add GitHub CI workflow
+
+Once you have your API key, you can start uploading OpenAPI specifications on every API build. We'll use our [GitHub Action](https://github.com/marketplace/actions/upload-openapi-spec-by-hey-api), but you can also make the API call manually if you're not using GitHub.
+
+Create a new GitHub workflow or add an upload step to an existing workflow inside your API codebase. The example below will upload your OpenAPI specification to Hey API on every pull request and push to the `main` branch.
 
 ```yaml
 name: Upload OpenAPI Specification
@@ -22,6 +41,7 @@ on:
   push:
     branches:
       - main
+  pull_request:
 
 jobs:
   upload-openapi-spec:
@@ -31,14 +51,147 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Upload OpenAPI spec
-        uses: hey-api/upload-openapi-spec@v1
+        uses: hey-api/upload-openapi-spec@v1.3.0
         with:
-          hey-api-token: ${{ secrets.HEY_API_TOKEN }}
-          path-to-openapi: path/to/openapi.json
+          path-to-file: path/to/openapi.json
+          tags: optional,custom,tags
+        env:
+          API_KEY: ${{ secrets.HEY_API_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Inputs
+
+To successfully upload an OpenAPI specification, you need to provide the following inputs (see `with` in the example above)
+
+#### `path-to-file`
+
+A relative path to your OpenAPI file within the repository. Note that you might need an additional step in your GitHub workflow to generate this file (see [FastAPI example](https://fastapi.tiangolo.com/how-to/extending-openapi/#generate-the-openapi-schema)).
+
+#### `tags` (optional)
+
+A comma-separated string value representing any custom tags you wish to add to your OpenAPI specification.
+
+### Environment Variables
+
+In addition to the required `path-to-file` input, you must provide the following environment variables.
+
+#### `API_KEY`
+
+This is the project API key you obtained from [Hey API](https://app.heyapi.dev/).
+
+::: warning
+Personal API keys can't be used to upload specifications.
+:::
+
+#### `GITHUB_TOKEN`
+
+This variable will be available inside your workflow by default. It's used to
+fetch information about your repository, i.e. default branch.
+
+## Generate Clients
+
+You can generate clients from public projects or any private projects you can access. The setup is largely the same, you want to configure the input path used by your codegen.
+
+::: code-group
+
+```sh [Hey API]
+npx @hey-api/openapi-ts \
+  -i https://get.heyapi.dev/hey-api/backend \
+  -o src/client \
+  -c @hey-api/client-fetch
+```
+
+```sh [OpenAPI TypeScript]
+npx openapi-typescript \
+  https://get.heyapi.dev/hey-api/backend \
+  -o schema.ts
+```
+
+```sh [Orval]
+npx orval \
+  --input https://get.heyapi.dev/hey-api/backend \
+  --output ./src/client.ts
+```
+
+```sh [Other]
+other-cli \
+  --input https://get.heyapi.dev/hey-api/backend \  # [!code ++]
+  --output refer/to/other/tools/docs
+```
+
+:::
+
+By default, we preserve the current behavior and return the latest specification. Let's have a closer look at the input path and change that.
+
+## Get API
+
+As you can deduce from the examples above, the default command for fetching OpenAPI specifications looks like this.
+
+```
+https://get.heyapi.dev/<organization>/<project>
+```
+
+If you created an organization `foo` with project `bar` earlier, your URL would look like this.
+
+```
+https://get.heyapi.dev/foo/bar
+```
+
+### Auth
+
+Projects are private by default, you will need to be authenticated to download OpenAPI specifications. We recommend using [project API keys](#prerequisites) in CI workflows and [personal API keys](https://app.heyapi.dev/settings/user/apis) for local development.
+
+Once you have your API key, you can authenticate the request using the `Authorization` header or `api_key` query parameter.
+
+```
+https://get.heyapi.dev/foo/bar?api_key=<my_api_key>
+```
+
+Congratulations on fetching your first OpenAPI specification! 🎉
+
+### Filters
+
+The default behavior returns the last uploaded specification. This might not be what you want. You can use a range of filters to narrow down the possible specifications, or pin your builds to an exact version.
+
+#### `branch`
+
+You can fetch the last build from branch by providing the `branch` query parameter.
+
+```
+https://get.heyapi.dev/foo/bar?branch=production
+```
+
+#### `commit_sha`
+
+You can fetch an exact specification by providing the `commit_sha` query parameter. This will always return the same file.
+
+```
+https://get.heyapi.dev/foo/bar?commit_sha=0eb34c2024841ce95620f3ec02a2fea164ea4e9d
 ```
 
-This step requires you to register with us in order to obtain a Hey API token. Please follow the instructions in our [GitHub Action](https://github.com/marketplace/actions/upload-openapi-spec-by-hey-api) to complete the setup. Once you have your APIs configured, you're ready to connect your clients.
+#### `tags`
+
+If you're tagging your specifications with [custom tags](#tags-optional), you can use them to filter the results. When you provide multiple tags, only the first match will be returned.
+
+```
+https://get.heyapi.dev/foo/bar?tags=optional,custom,tags
+```
+
+#### `version`
+
+Every OpenAPI document contains a required version field. You can use this value to fetch the last uploaded specification matching the value.
+
+```
+https://get.heyapi.dev/foo/bar?version=1.0.0
+```
+
+## Feedback
+
+We'd love your feedback! You can contact us on social media (search Hey API), [email](mailto:[email protected]), or [GitHub](https://github.com/orgs/hey-api/discussions/1773).
+
+## Pricing
 
-## Configure Clients
+The platform is currently in beta with our focus being on delivering a great experience. We plan to announce pricing once we have gathered enough data around usage patterns. However, we can guarantee there will always be a free plan available. Our mission to bring the finest tooling for working with APIs remains unchanged.
 
-More information will be provided as we finalize the tooling.
+<!--@include: ../sponsors.md-->

packages/client-axios/README.md

@@ -15,6 +15,11 @@
 - granular request and response customization options
 - minimal learning curve thanks to extending the underlying technology
 - support bundling inside the generated output
+- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
+
+## Platform
+
+Our platform for OpenAPI specifications is now available. Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations).
 
 ## Documentation
 
@@ -30,10 +35,6 @@ Love Hey API? Become our [sponsor](https://github.com/sponsors/hey-api).
   </a>
 </p>
 
-## GitHub Integration (coming soon)
-
-Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
-
 ## Migration Guides
 
-[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)

packages/client-fetch/README.md

@@ -15,6 +15,11 @@
 - granular request and response customization options
 - minimal learning curve thanks to extending the underlying technology
 - support bundling inside the generated output
+- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
+
+## Platform
+
+Our platform for OpenAPI specifications is now available. Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations).
 
 ## Documentation
 
@@ -30,10 +35,6 @@ Love Hey API? Become our [sponsor](https://github.com/sponsors/hey-api).
   </a>
 </p>
 
-## GitHub Integration (coming soon)
-
-Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
-
 ## Migration Guides
 
-[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)

packages/client-next/README.md

@@ -16,6 +16,11 @@
 - granular request and response customization options
 - minimal learning curve thanks to extending the underlying technology
 - support bundling inside the generated output
+- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
+
+## Platform
+
+Our platform for OpenAPI specifications is now available. Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations).
 
 ## Documentation
 
@@ -31,10 +36,6 @@ Love Hey API? Become our [sponsor](https://github.com/sponsors/hey-api).
   </a>
 </p>
 
-## GitHub Integration (coming soon)
-
-Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
-
 ## Migration Guides
 
-[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)

packages/client-nuxt/README.md

@@ -16,6 +16,11 @@
 - granular request and response customization options
 - minimal learning curve thanks to extending the underlying technology
 - support bundling inside the generated output
+- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
+
+## Platform
+
+Our platform for OpenAPI specifications is now available. Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations).
 
 ## Documentation
 
@@ -31,10 +36,6 @@ Love Hey API? Become our [sponsor](https://github.com/sponsors/hey-api).
   </a>
 </p>
 
-## GitHub Integration (coming soon)
-
-Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
-
 ## Migration Guides
 
-[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)