fork of hey-api/openapi-ts because I need some additional things
Merge pull request #1774 from hey-api/docs/platform-guide
docs: announce Hey API platform
+213
-43
+10
.changeset/good-ligers-matter.md
+10
.changeset/good-ligers-matter.md
+5
-4
README.md
+5
-4
README.md
···
36
36
- generates TypeScript interfaces and SDKs
37
37
- Fetch API, Axios, Nuxt, Angular, Node.js, and XHR clients available
38
38
- plugin ecosystem to reduce third-party boilerplate
39
+
- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
40
+
41
+
## Platform
42
+
43
+
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).
39
44
40
45
## Sponsors
41
46
···
46
51
<img alt="Stainless logo" height="50" src="https://heyapi.dev/images/stainless-logo-wordmark-480w.jpeg" />
47
52
</a>
48
53
</p>
49
-
50
-
## GitHub Integration (coming 2025)
51
-
52
-
Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
53
54
54
55
## Quick Start
55
56
+1
-1
docs/.vitepress/config/en.ts
+1
-1
docs/.vitepress/config/en.ts
+1
-1
docs/index.md
+1
-1
docs/index.md
···
40
40
link: /openapi-ts/plugins
41
41
linkText: Learn more
42
42
- 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>
43
-
title: Integrations <span data-soon>Soon</span>
43
+
title: Integrations
44
44
details: Automatically update your code when the APIs it depends on change. Works with any codegen.
45
45
link: /openapi-ts/integrations
46
46
linkText: Find out more
+1
docs/openapi-ts/get-started.md
+1
docs/openapi-ts/get-started.md
···
29
29
- generates TypeScript interfaces and SDKs
30
30
- Fetch API, Axios, Nuxt, Angular, Node.js, and XHR clients available
31
31
- plugin ecosystem to reduce third-party boilerplate
32
+
- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
32
33
33
34
## Quick Start
34
35
+166
-13
docs/openapi-ts/integrations.md
+166
-13
docs/openapi-ts/integrations.md
···
1
1
---
2
-
title: Integrations
3
-
description: Automate your client generation.
2
+
title: Hey API Platform
3
+
description: Automate your client generation with our OpenAPI specifications storage.
4
4
---
5
5
6
-
# Integrations <span data-soon>Soon</span>
6
+
# Hey API Platform
7
7
8
8
::: warning
9
-
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).
9
+
This feature is in development! :tada: Try it out and provide feedback on [GitHub](https://github.com/orgs/hey-api/discussions/1773).
10
10
:::
11
11
12
-
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.
12
+
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.
13
+
14
+
## Features
15
+
16
+
- API version history
17
+
- real-time updates
18
+
- reproducible builds
19
+
- language and codegen agnostic (TypeScript/Python/Go/Java/etc codegens are welcome)
20
+
21
+
## Upload Specifications
22
+
23
+
Before you can generate clients, you must publish your OpenAPI specifications to Hey API.
24
+
25
+
### Prerequisites
26
+
27
+
1. Create a **free account** with [Hey API](https://app.heyapi.dev/).
28
+
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.
29
+
1. Inside your project, go to _Integrations_ > _APIs_ and generate an **API key**. Keep this value secret, it will be used to upload files.
30
+
31
+
### Add GitHub CI workflow
13
32
14
-
## Upload OpenAPI Spec
33
+
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.
15
34
16
-
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.
35
+
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.
17
36
18
37
```yaml
19
38
name: Upload OpenAPI Specification
···
22
41
push:
23
42
branches:
24
43
- main
44
+
pull_request:
25
45
26
46
jobs:
27
47
upload-openapi-spec:
···
31
51
uses: actions/checkout@v4
32
52
33
53
- name: Upload OpenAPI spec
34
-
uses: hey-api/upload-openapi-spec@v1
54
+
uses: hey-api/upload-openapi-spec@v1.3.0
35
55
with:
36
-
hey-api-token: ${{ secrets.HEY_API_TOKEN }}
37
-
path-to-openapi: path/to/openapi.json
56
+
path-to-file: path/to/openapi.json
57
+
tags: optional,custom,tags
58
+
env:
59
+
API_KEY: ${{ secrets.HEY_API_TOKEN }}
60
+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
61
+
```
62
+
63
+
### Inputs
64
+
65
+
To successfully upload an OpenAPI specification, you need to provide the following inputs (see `with` in the example above)
66
+
67
+
#### `path-to-file`
68
+
69
+
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)).
70
+
71
+
#### `tags` (optional)
72
+
73
+
A comma-separated string value representing any custom tags you wish to add to your OpenAPI specification.
74
+
75
+
### Environment Variables
76
+
77
+
In addition to the required `path-to-file` input, you must provide the following environment variables.
78
+
79
+
#### `API_KEY`
80
+
81
+
This is the project API key you obtained from [Hey API](https://app.heyapi.dev/).
82
+
83
+
::: warning
84
+
Personal API keys can't be used to upload specifications.
85
+
:::
86
+
87
+
#### `GITHUB_TOKEN`
88
+
89
+
This variable will be available inside your workflow by default. It's used to
90
+
fetch information about your repository, i.e. default branch.
91
+
92
+
## Generate Clients
93
+
94
+
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.
95
+
96
+
::: code-group
97
+
98
+
```sh [Hey API]
99
+
npx @hey-api/openapi-ts \
100
+
-i https://get.heyapi.dev/hey-api/backend \
101
+
-o src/client \
102
+
-c @hey-api/client-fetch
103
+
```
104
+
105
+
```sh [OpenAPI TypeScript]
106
+
npx openapi-typescript \
107
+
https://get.heyapi.dev/hey-api/backend \
108
+
-o schema.ts
109
+
```
110
+
111
+
```sh [Orval]
112
+
npx orval \
113
+
--input https://get.heyapi.dev/hey-api/backend \
114
+
--output ./src/client.ts
115
+
```
116
+
117
+
```sh [Other]
118
+
other-cli \
119
+
--input https://get.heyapi.dev/hey-api/backend \ # [!code ++]
120
+
--output refer/to/other/tools/docs
121
+
```
122
+
123
+
:::
124
+
125
+
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.
126
+
127
+
## Get API
128
+
129
+
As you can deduce from the examples above, the default command for fetching OpenAPI specifications looks like this.
130
+
131
+
```
132
+
https://get.heyapi.dev/<organization>/<project>
133
+
```
134
+
135
+
If you created an organization `foo` with project `bar` earlier, your URL would look like this.
136
+
137
+
```
138
+
https://get.heyapi.dev/foo/bar
139
+
```
140
+
141
+
### Auth
142
+
143
+
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.
144
+
145
+
Once you have your API key, you can authenticate the request using the `Authorization` header or `api_key` query parameter.
146
+
147
+
```
148
+
https://get.heyapi.dev/foo/bar?api_key=<my_api_key>
149
+
```
150
+
151
+
Congratulations on fetching your first OpenAPI specification! 🎉
152
+
153
+
### Filters
154
+
155
+
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.
156
+
157
+
#### `branch`
158
+
159
+
You can fetch the last build from branch by providing the `branch` query parameter.
160
+
161
+
```
162
+
https://get.heyapi.dev/foo/bar?branch=production
38
163
```
39
164
40
-
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.
165
+
#### `commit_sha`
41
166
42
-
## Configure Clients
167
+
You can fetch an exact specification by providing the `commit_sha` query parameter. This will always return the same file.
168
+
169
+
```
170
+
https://get.heyapi.dev/foo/bar?commit_sha=0eb34c2024841ce95620f3ec02a2fea164ea4e9d
171
+
```
172
+
173
+
#### `tags`
43
174
44
-
More information will be provided as we finalize the tooling.
175
+
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.
176
+
177
+
```
178
+
https://get.heyapi.dev/foo/bar?tags=optional,custom,tags
179
+
```
180
+
181
+
#### `version`
182
+
183
+
Every OpenAPI document contains a required version field. You can use this value to fetch the last uploaded specification matching the value.
184
+
185
+
```
186
+
https://get.heyapi.dev/foo/bar?version=1.0.0
187
+
```
188
+
189
+
## Feedback
190
+
191
+
We'd love your feedback! You can contact us on social media (search Hey API), [email](mailto:lubos@heyapi.dev), or [GitHub](https://github.com/orgs/hey-api/discussions/1773).
192
+
193
+
## Pricing
194
+
195
+
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.
196
+
197
+
<!--@include: ../sponsors.md-->
+6
-5
packages/client-axios/README.md
+6
-5
packages/client-axios/README.md
···
15
15
- granular request and response customization options
16
16
- minimal learning curve thanks to extending the underlying technology
17
17
- support bundling inside the generated output
18
+
- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
19
+
20
+
## Platform
21
+
22
+
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).
18
23
19
24
## Documentation
20
25
···
30
35
</a>
31
36
</p>
32
37
33
-
## GitHub Integration (coming soon)
34
-
35
-
Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
36
-
37
38
## Migration Guides
38
39
39
-
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
40
+
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)
+6
-5
packages/client-fetch/README.md
+6
-5
packages/client-fetch/README.md
···
15
15
- granular request and response customization options
16
16
- minimal learning curve thanks to extending the underlying technology
17
17
- support bundling inside the generated output
18
+
- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
19
+
20
+
## Platform
21
+
22
+
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).
18
23
19
24
## Documentation
20
25
···
30
35
</a>
31
36
</p>
32
37
33
-
## GitHub Integration (coming soon)
34
-
35
-
Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
36
-
37
38
## Migration Guides
38
39
39
-
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
40
+
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)
+6
-5
packages/client-next/README.md
+6
-5
packages/client-next/README.md
···
16
16
- granular request and response customization options
17
17
- minimal learning curve thanks to extending the underlying technology
18
18
- support bundling inside the generated output
19
+
- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
20
+
21
+
## Platform
22
+
23
+
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).
19
24
20
25
## Documentation
21
26
···
31
36
</a>
32
37
</p>
33
38
34
-
## GitHub Integration (coming soon)
35
-
36
-
Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
37
-
38
39
## Migration Guides
39
40
40
-
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
41
+
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)
+6
-5
packages/client-nuxt/README.md
+6
-5
packages/client-nuxt/README.md
···
16
16
- granular request and response customization options
17
17
- minimal learning curve thanks to extending the underlying technology
18
18
- support bundling inside the generated output
19
+
- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
20
+
21
+
## Platform
22
+
23
+
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).
19
24
20
25
## Documentation
21
26
···
31
36
</a>
32
37
</p>
33
38
34
-
## GitHub Integration (coming soon)
35
-
36
-
Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
37
-
38
39
## Migration Guides
39
40
40
-
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen)
41
+
[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating#openapi-typescript-codegen)
+5
-4
packages/openapi-ts/README.md
+5
-4
packages/openapi-ts/README.md
···
36
36
- generates TypeScript interfaces and SDKs
37
37
- Fetch API, Axios, Nuxt, Angular, Node.js, and XHR clients available
38
38
- plugin ecosystem to reduce third-party boilerplate
39
+
- [platform](https://heyapi.dev/openapi-ts/integrations) for automating codegen builds
40
+
41
+
## Platform
42
+
43
+
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).
39
44
40
45
## Sponsors
41
46
···
46
51
<img alt="Stainless logo" height="50" src="https://heyapi.dev/images/stainless-logo-wordmark-480w.jpeg" />
47
52
</a>
48
53
</p>
49
-
50
-
## GitHub Integration (coming 2025)
51
-
52
-
Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
53
54
54
55
## Quick Start
55
56