mokkenstorm.dev
fork of hey-api/openapi-ts because I need some additional things
Add documentation for examples workflow
Co-authored-by: mrlubos <12529395+mrlubos@users.noreply.github.com>
+130
+46
docs/openapi-ts/community/contributing/developing.md
+46
docs/openapi-ts/community/contributing/developing.md
···
8
8
::: warning
9
9
This page is under construction. We appreciate your patience.
10
10
:::
11
+
12
+
## Working with Examples
13
+
14
+
The `examples` folder contains various integration examples that demonstrate how to use `@hey-api/openapi-ts` with different frameworks and libraries. These examples are kept in sync with the codebase through automated checks.
15
+
16
+
### Generating Example Code
17
+
18
+
When you make changes to the core packages that affect code generation, you need to regenerate the client code in all examples:
19
+
20
+
```bash
21
+
pnpm examples:generate
22
+
```
23
+
24
+
This command will:
25
+
26
+
- Find all examples with an `openapi-ts` script
27
+
- Run the OpenAPI code generator for each example
28
+
- Update the generated client code in each example
29
+
30
+
### Checking Example Code
31
+
32
+
Before committing changes, ensure that all generated example code is up-to-date:
33
+
34
+
```bash
35
+
pnpm examples:check
36
+
```
37
+
38
+
This command will:
39
+
40
+
- Regenerate all example code
41
+
- Check if any files were modified
42
+
- Exit with an error if generated code is out of sync
43
+
44
+
This check is also run automatically in CI to ensure examples stay in sync with the main codebase.
45
+
46
+
### Example Workflow
47
+
48
+
1. Make changes to core packages
49
+
2. Build the packages: `pnpm build --filter="@hey-api/**"`
50
+
3. Regenerate examples: `pnpm examples:generate`
51
+
4. Commit all changes including the updated generated code
52
+
5. The CI will verify that examples are in sync
53
+
54
+
::: tip
55
+
Think of generated example code as snapshot tests - they should always reflect the current state of the code generator.
56
+
:::
+84
examples/README.md
+84
examples/README.md
···
1
+
# Examples
2
+
3
+
This directory contains integration examples demonstrating how to use `@hey-api/openapi-ts` with various frameworks, libraries, and client implementations.
4
+
5
+
## Available Examples
6
+
7
+
- **openapi-ts-angular** - Angular integration with common HTTP client
8
+
- **openapi-ts-angular-common** - Angular with @angular/common/http
9
+
- **openapi-ts-axios** - Using Axios client
10
+
- **openapi-ts-fastify** - Fastify server integration
11
+
- **openapi-ts-fetch** - Native Fetch API client
12
+
- **openapi-ts-next** - Next.js integration
13
+
- **openapi-ts-nuxt** - Nuxt.js integration with plugin
14
+
- **openapi-ts-ofetch** - Using ofetch client
15
+
- **openapi-ts-openai** - OpenAI API integration
16
+
- **openapi-ts-pinia-colada** - Vue with Pinia Colada state management
17
+
- **openapi-ts-sample** - Sample/template example (excluded from CI)
18
+
- **openapi-ts-tanstack-angular-query-experimental** - Angular with TanStack Query
19
+
- **openapi-ts-tanstack-react-query** - React with TanStack Query
20
+
- **openapi-ts-tanstack-svelte-query** - Svelte with TanStack Query
21
+
- **openapi-ts-tanstack-vue-query** - Vue with TanStack Query
22
+
23
+
## Generated Code
24
+
25
+
All examples (except `openapi-ts-sample`) contain generated client code that is **committed to the repository**. This ensures:
26
+
27
+
1. Examples always reflect the current state of the code generator
28
+
2. Changes to the code generator are visible in pull requests
29
+
3. CI can verify that examples are kept up-to-date
30
+
31
+
## Regenerating Examples
32
+
33
+
After making changes to the core packages, regenerate all example code:
34
+
35
+
```bash
36
+
pnpm examples:generate
37
+
```
38
+
39
+
This command will run `openapi-ts` for each example that has an `openapi-ts` script in its `package.json`.
40
+
41
+
## Verifying Examples
42
+
43
+
To check if all examples are up-to-date with the current codebase:
44
+
45
+
```bash
46
+
pnpm examples:check
47
+
```
48
+
49
+
This check is also run automatically in CI. If it fails, run `pnpm examples:generate` and commit the changes.
50
+
51
+
## Running Examples
52
+
53
+
Each example can be run individually using the `example` script:
54
+
55
+
```bash
56
+
# Run dev server for fetch example
57
+
pnpm example fetch dev
58
+
59
+
# Build fetch example
60
+
pnpm example fetch build
61
+
```
62
+
63
+
Or directly using pnpm filters:
64
+
65
+
```bash
66
+
pnpm --filter @example/openapi-ts-fetch dev
67
+
```
68
+
69
+
## Creating New Examples
70
+
71
+
When creating a new example:
72
+
73
+
1. Create a new directory in `examples/`
74
+
2. Add an `openapi-ts` script to `package.json`
75
+
3. Run `pnpm examples:generate` to create initial generated code
76
+
4. Commit both the source and generated code
77
+
5. The example will automatically be included in CI checks
78
+
79
+
## Excluding Examples
80
+
81
+
To exclude an example from CI (like `openapi-ts-sample`):
82
+
83
+
1. Remove the `openapi-ts` script from `package.json`, or
84
+
2. Update the exclusion filters in `package.json` scripts and `.github/workflows/ci.yml`