fork of hey-api/openapi-ts because I need some additional things
docs: remove plugin README, move content to PR description
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-51
-51
packages/openapi-ts/src/plugins/nestjs/README.md
-51
packages/openapi-ts/src/plugins/nestjs/README.md
···
1
-
# NestJS Plugin
2
-
3
-
Generate per-tag `ControllerMethods` type aliases from OpenAPI specs for NestJS controllers.
4
-
5
-
## Design Decisions
6
-
7
-
| Decision | Choice | Rationale |
8
-
| --------------------- | ---------------------------------------------- | ----------------------------------------------------------- |
9
-
| Output format | Per-tag `{Tag}ControllerMethods` type aliases | Maps 1:1 to NestJS one-controller-per-resource pattern |
10
-
| `type` vs `interface` | `type` alias | DSL produces `type` aliases; both work with `implements` |
11
-
| Parameters | Individual: `path`, `query`, `body`, `headers` | Maps 1:1 to `@Param()`, `@Query()`, `@Body()`, `@Headers()` |
12
-
| Parameter ordering | Required before optional | Prevents TS error when optional precedes required |
13
-
| Return type | `Promise<OperationResponse>` | Controllers return values, not status-code maps |
14
-
| Config options | None | Zero config = fastest path to value |
15
-
| Untagged operations | `DefaultControllerMethods` | Consistent fallback |
16
-
| `includeInEntry` | `false` | Users import from `nestjs.gen.ts` directly |
17
-
18
-
## Constraints
19
-
20
-
**`implements` requires whole-object parameter style:**
21
-
22
-
```typescript
23
-
// WORKS — whole-object style
24
-
async showPetById(@Param() path: ShowPetByIdData['path']) { ... }
25
-
26
-
// BREAKS — decomposed style (different signature than generated type)
27
-
async showPetById(@Param('petId') petId: string) { ... }
28
-
```
29
-
30
-
**Incompatible patterns:**
31
-
32
-
- `@Res()` — extra parameter breaks assignability
33
-
- `@UploadedFile()` — bypass `implements` for file upload methods
34
-
- SSE endpoints — `Observable<MessageEvent>` doesn't match `Promise<T>`
35
-
36
-
**Not generated:**
37
-
38
-
- Cookie parameters — NestJS handles cookies via `@Req()` or cookie middleware, not method params
39
-
- Error responses — NestJS handles errors via exception filters
40
-
41
-
## Edge Cases
42
-
43
-
| Case | Handling |
44
-
| ----------------------- | -------------------------------------------- |
45
-
| No operationId | Auto-generated by `operationToId()` |
46
-
| Duplicate operation IDs | Numeric suffix (`result2`, `result3`) |
47
-
| Invalid TS identifiers | Sanitized by `sanitizeNamespaceIdentifier()` |
48
-
| No parameters | `() => Promise<T>` |
49
-
| No response body (204) | `Promise<void>` |
50
-
| Multiple tags | First tag wins |
51
-
| Non-ASCII in tags/names | Handled |