knowject-api-to-types

Category: Development & Coding | Uploader: lynxlangya | Downloads: 0 | Version: v1.0（Latest）

Use when the user wants to generate TypeScript types from an OpenAPI document and wire them into the typed client produced by knowject-read-api. Triggers on phrases like "/knowject types", "把 openapi 转成 types", "给 read-api client 补类型", "生成 typed client 的类型", "rewrite the unknown placeholders", "wire types into the generated client". Day-1 input is OpenAPI 3 only — non-OpenAPI inputs (Express routes, Mongoose, Zod, Pydantic, Spring DTOs, Nest decorators, markdown specs, etc.) are refused with framework-specific recommendations for exposing OpenAPI.

Changelog: Source: GitHub https://github.com/lynxlangya/knowject

Directory Structure

Current level: tree/main/skills/knowject-api-to-types/

📁 agents/
- 📄 openai.yaml 939 B
📁 references/
- 📁 examples/
  - 📄 client-input.ts 493 B
  - 📄 client-rewritten-expected.ts 557 B
  - 📄 openapi-input.yaml 1.9 KB
  - 📄 types-extraction-expected.json 1.0 KB
  - 📄 types-output-expected.ts 469 B
- 📄 non-openapi-refusal.md 2.7 KB
- 📄 openapi-to-typescript-mapping.md 3.0 KB
- 📄 typed-client-rewrite.md 3.4 KB
📁 scripts/
- 📄 extract-types-from-openapi.py 7.4 KB
- 📄 rewrite-typed-client.py 4.5 KB
📄 SKILL.md 8.2 KB

SKILL.md

---
name: knowject-api-to-types
description: |
  Use when the user wants to generate TypeScript types from an OpenAPI document and
  wire them into the typed client produced by knowject-read-api. Triggers on phrases
  like "/knowject types", "把 openapi 转成 types", "给 read-api client 补类型", "生成
  typed client 的类型", "rewrite the unknown placeholders", "wire types into the
  generated client". Day-1 input is OpenAPI 3 only — non-OpenAPI inputs (Express
  routes, Mongoose, Zod, Pydantic, Spring DTOs, Nest decorators, markdown specs,
  etc.) are refused with framework-specific recommendations for exposing OpenAPI.
  Two output modes: (1) primary — emit a sibling <module>.types.ts and rewrite
  request<unknown>(...) in the read-api client to request<X>(...); (2) fallback —
  emit types-only when no read-api client file is found. Both modes use the
  diff-first / confirm-before-write safety gate established in Phase 2.
---

# `knowject-api-to-types`

You generate TypeScript types from an OpenAPI 3 document and wire them into the typed client that `knowject-read-api` produced.

## Hard rules

1. **OpenAPI 3 input only.** If `api.sources[*].format` is anything else (`express` / `fastapi` / `nest` / `markdown` / etc.), refuse and recommend the matching OpenAPI exposure tool per [`references/non-openapi-refusal.md`](./references/non-openapi-refusal.md). Do not attempt native parsing.
2. **Refuse without `knowject/context.yaml`.** Point at `knowject-context-init`, stop.
3. **Refuse without `api.client.output_dir`.** Cannot decide where to write `.types.ts`; ask the user, do not assume.
4. **Header-marker contract.** The rewriter only modifies files whose content includes `Generated by knowject-read-api`. Files without this marker are never written to by this Skill.
5. **Never overwrite silently.** Show the unified diff of every file change and require confirmation before any write.
6. **Use the user's language** for chat replies; generated TypeScript is always English.
7. **Day-1 scope is response types only.** `request<unknown>` becomes `request<X>`. The `body: unknown` parameter stays `unknown`; request-body typing is a v2 extension. See "What this Skill does NOT do" below.

## Flow

### Step 1 — Verify preconditions

Read `knowject/context.yaml`:

- File exists. Else → point at `knowject-context-init`, stop.
- `api.sources` non-empty. Else → tell the user to run `knowject-read-api` first or add an OpenAPI source via `knowject-context-init`, stop.
- For each source: if `format` is not `openapi`, apply the refusal recipe from [`references/non-openapi-refusal.md`](./references/non-openapi-refusal.md). Process only OpenAPI sources.
- `api.client.output_dir` present. Else → ask the user once, then proceed.

### Step 2 — Derive the module name

Per OpenAPI source, derive a module name:

- If the source path ends in `/<name>.yaml` or `/<name>.json` → use `<name>`.
- Else if the source is a directory → use its basename.
- Else → ask the user.

The module name drives the output filenames (`<module>.types.ts`) and the type-import path in the rewritten client.

### Step 3 — Extract types

Run:

```bash
python3 <SKILLS_ROOT>/knowject-api-to-types/scripts/extract-types-from-openapi.py \
  <openapi-source-path> --module <module-name>
```

Cache the JSON output (`{module, types_ts, operations_mapping}`) in memory and write the same JSON to a temp file if Mode A will run the rewriter.

If the extractor exits non-zero, surface its stderr to the user and stop. PyYAML missing (exit 3) → tell the user `pip install pyyaml`.

### Step 4 — Pick the output mode

Look for `<api.client.output_dir>/<module>.ts`:

- **File exists AND contains `Generated by knowject-read-api`** → **Mode A (rewrite)**. Proceed to Step 5A.
- **File missing, or file exists but lacks the marker** → **Mode B (emit-only)**. Proceed to Step 5B.

### Step 5A — Mode A: emit types + rewrite client

1. Write the `types_ts` content and the full extraction JSON to temp locations.
2. Run:

   ```bash
   python3 <SKILLS_ROOT>/knowject-api-to-types/scripts/rewrite-typed-client.py \
     <api.client.output_dir>/<module>.ts \
     <path-to-extraction-json> \
     <module>
   ```

3. Show the user **two diffs**:
   - The new file `<module>.types.ts` (it does not exist on disk yet).
   - The diff of `<module>.ts` (existing client → rewritten client).
4. Ask: "Apply both changes? (yes / types-only / cancel)".
5. On `yes` → write both files. On `types-only` → write only the types file, skip the client rewrite. On `cancel` → stop, nothing written.

### Step 5B — Mode B: emit types only

1. Show the user the diff of the new `<module>.types.ts` (does not exist on disk yet).
2. Ask: "Write `<module>.types.ts`? (yes / cancel)".
3. On `yes` → write the file. Output:

   ```
   <module>.types.ts written. No read-api typed client found at
   <api.client.output_dir>/<module>.ts — wire the types manually, or
   run knowject-read-api first and then re-run this Skill to enable
   the automatic rewrite.
   ```

### Step 6 — Summarize

Output:

- Files written / skipped.
- Per-endpoint summary from the rewriter's stderr (`rewrote` / `not_found` / `no_response_type`).
- The next-step hint: "Re-run TypeScript checks (`tsc --noEmit` or your equivalent) to validate the new types compile against your code."

## Failure modes

- **`knowject/context.yaml` missing or `api` block incomplete:** name the missing fields, point at `knowject-context-init`, stop.
- **`api.sources[*].format` is not `openapi`:** apply [`references/non-openapi-refusal.md`](./references/non-openapi-refusal.md), stop.
- **OpenAPI source path does not exist on disk:** print the expected path verbatim, ask the user whether the file moved.
- **OpenAPI document fails to parse (not a mapping, or PyYAML chokes):** show stderr verbatim, ask whether the file is OpenAPI 3.
- **Extractor produces empty `operations_mapping` (no operations in the OpenAPI doc):** tell the user "the OpenAPI document contains no operations — nothing to type", stop.
- **Rewriter refuses (no header marker):** **this is expected for user-authored files**; the Skill body downgrades to Mode B silently and writes types-only.
- **Rewriter reports `not_found` for one or more endpoints:** continue with partial wiring; surface the unmatched endpoints to the user with a one-line "wire these by hand" hint.
- **`api.client.output_dir` does not exist on disk:** create it (after user confirmation) before writing.

## What this Skill does NOT do

- **Does not generate runtime validators** (zod / io-ts / yup). Output is TypeScript declarations only (`interface` for object schemas, `type` aliases for non-object schemas). Runtime validation is a separate v2 product candidate.
- **Does not type request bodies, query params, or path params.** Day-1 scope is response types only. Request types are emitted in `<module>.types.ts` for manual wiring; future v2 will extend the rewriter to import and apply them.
- **Does not parse non-OpenAPI sources.** No Express AST, no Mongoose models, no Zod inference, no Pydantic, no Spring DTOs, no Nest decorators, no markdown. Refuse with [`references/non-openapi-refusal.md`](./references/non-openapi-refusal.md).
- **Does not merge into existing `import` blocks.** The new `import type` line is prepended when at least one response type was rewritten; if your project conventions require it elsewhere, move it after Skill output.
- **Does not modify the read-api client's function signatures, parameters, or behavior.** Only the `request<unknown>` generic argument changes.
- **Does not run TypeScript / lint / test against the output.** That is the user's existing workflow.

## See also

- OpenAPI → TS mapping rules: [`references/openapi-to-typescript-mapping.md`](./references/openapi-to-typescript-mapping.md)
- Rewrite flow: [`references/typed-client-rewrite.md`](./references/typed-client-rewrite.md)
- Non-OpenAPI refusal recipes: [`references/non-openapi-refusal.md`](./references/non-openapi-refusal.md)
- Examples: [`references/examples/`](./references/examples/)
- Product design: [`../ROADMAP.md`](../ROADMAP.md) Decision log entries for the 2026-05-17 narrowing and Phase 3 ship
- Schema reference: [`../_shared/context-yaml-schema.md`](../_shared/context-yaml-schema.md)

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

knowject-api-to-types

Directory Structure

SKILL.md

Report

Notice