Openapi To Typescript

softaworks/agent-toolkit/skills/openapi-to-typescript

作者 softaworks3027f20f3181無授權條款2.5K 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫7 個月前更新

Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards. This skill should be used when the user asks to generate types from OpenAPI, convert schema to TS, create API interfaces, or generate TypeScript types from an API specification.

僅含說明Software Development
AI 產生的概覽

將 OpenAPI 3.0 JSON 或 YAML 規格轉換為 TypeScript 介面、請求／回應型別與型別守衛。

功能
讀取 OpenAPI 3.0.x 規格檔案並進行驗證，從 components/schemas 擷取資料結構、從 paths 擷取端點。接著產生一個 TypeScript 檔案，內含匯出的介面、請求與回應型別、型別守衛，以及標準的 ApiError 型別，並對應 OpenAPI 的基本型別、格式、列舉、陣列、oneOf 與 allOf 結構。產生的檔案會寫入指定位置，預設為目前目錄下的 types/api.ts。
適用情境
當你需要依 OpenAPI 規格產生 TypeScript 型別時使用，例如建立 API 介面或將 schema 轉成 TS。適合「從規格產生型別」或產生具型別 API 模型這類需求。
執行需求
需要一份 JSON 或 YAML 格式的 OpenAPI 3.0.x 檔案作為輸入，以及可寫入的 TypeScript 輸出路径。此技能未附帶指令碼，僅提供操作說明。

OpenAPI to TypeScript

Converts OpenAPI 3.0 specifications to TypeScript interfaces and type guards.

Input: OpenAPI file (JSON or YAML) Output: TypeScript file with interfaces and type guards

When to Use

  • "generate types from openapi"
  • "convert openapi to typescript"
  • "create API interfaces"
  • "generate types from spec"

Workflow

  1. Request the OpenAPI file path (if not provided)
  2. Read and validate the file (must be OpenAPI 3.0.x)
  3. Extract schemas from components/schemas
  4. Extract endpoints from paths (request/response types)
  5. Generate TypeScript (interfaces + type guards)
  6. Ask where to save (default: types/api.ts in current directory)
  7. Write the file

OpenAPI Validation

Check before processing:

- Field "openapi" must exist and start with "3.0"- Field "paths" must exist- Field "components.schemas" must exist (if there are types)

If invalid, report the error and stop.

Type Mapping

Primitives

OpenAPITypeScript
stringstring
numbernumber
integernumber
booleanboolean
nullnull

Format Modifiers

FormatTypeScript
uuidstring (comment UUID)
datestring (comment date)
date-timestring (comment ISO)
emailstring (comment email)
uristring (comment URI)

Complex Types

Object:

typescript
// OpenAPI: type: object, properties: {id, name}, required: [id]interface Example {  id: string;      // required: no ?  name?: string;   // optional: with ?}

Array:

typescript
// OpenAPI: type: array, items: {type: string}type Names = string[];

Enum:

typescript
// OpenAPI: type: string, enum: [active, draft]type Status = "active" | "draft";

oneOf (Union):

typescript
// OpenAPI: oneOf: [{$ref: Cat}, {$ref: Dog}]type Pet = Cat | Dog;

allOf (Intersection/Extends):

typescript
// OpenAPI: allOf: [{$ref: Base}, {type: object, properties: ...}]interface Extended extends Base {  extraField: string;}

Code Generation

File Header

typescript
/** * Auto-generated from: {source_file} * Generated at: {timestamp} * * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema */

Interfaces (from components/schemas)

For each schema in components/schemas:

typescript
export interface Product {  /** Product unique identifier */  id: string;
  /** Product title */  title: string;
  /** Product price */  price: number;
  /** Created timestamp */  created_at?: string;}
  • Use OpenAPI description as JSDoc
  • Fields in required[] have no ?
  • Fields outside required[] have ?

Request/Response Types (from paths)

For each endpoint in paths:

typescript
// GET /products - query paramsexport interface GetProductsRequest {  page?: number;  limit?: number;}
// GET /products - response 200export type GetProductsResponse = ProductList;
// POST /products - request bodyexport interface CreateProductRequest {  title: string;  price: number;}
// POST /products - response 201export type CreateProductResponse = Product;

Naming convention:

  • {Method}{Path}Request for params/body
  • {Method}{Path}Response for response

Type Guards

For each main interface, generate a type guard:

typescript
export function isProduct(value: unknown): value is Product {  return (    typeof value === 'object' &&    value !== null &&    'id' in value &&    typeof (value as any).id === 'string' &&    'title' in value &&    typeof (value as any).title === 'string' &&    'price' in value &&    typeof (value as any).price === 'number'  );}

Type guard rules:

  • Check typeof value === 'object' && value !== null
  • For each required field: check 'field' in value
  • For primitive fields: check typeof
  • For arrays: check Array.isArray()
  • For enums: check .includes()

Error Type (always include)

typescript
export interface ApiError {  status: number;  error: string;  detail?: string;}
export function isApiError(value: unknown): value is ApiError {  return (    typeof value === 'object' &&    value !== null &&    'status' in value &&    typeof (value as any).status === 'number' &&    'error' in value &&    typeof (value as any).error === 'string'  );}

$ref Resolution

When encountering {"$ref": "#/components/schemas/Product"}:

  1. Extract the schema name (Product)
  2. Use the type directly (don't resolve inline)
typescript
// OpenAPI: items: {$ref: "#/components/schemas/Product"}// TypeScript:items: Product[]  // reference, not inline

Complete Example

Input (OpenAPI):

json
{  "openapi": "3.0.0",  "components": {    "schemas": {      "User": {        "type": "object",        "properties": {          "id": {"type": "string", "format": "uuid"},          "email": {"type": "string", "format": "email"},          "role": {"type": "string", "enum": ["admin", "user"]}        },        "required": ["id", "email", "role"]      }    }  },  "paths": {    "/users/{id}": {      "get": {        "parameters": [{"name": "id", "in": "path", "required": true}],        "responses": {          "200": {            "content": {              "application/json": {                "schema": {"$ref": "#/components/schemas/User"}              }            }          }        }      }    }  }}

Output (TypeScript):

typescript
/** * Auto-generated from: api.openapi.json * Generated at: 2025-01-15T10:30:00Z * * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema */
// ============================================================================// Types// ============================================================================
export type UserRole = "admin" | "user";
export interface User {  /** UUID */  id: string;
  /** Email */  email: string;
  role: UserRole;}
// ============================================================================// Request/Response Types// ============================================================================
export interface GetUserByIdRequest {  id: string;}
export type GetUserByIdResponse = User;
// ============================================================================// Type Guards// ============================================================================
export function isUser(value: unknown): value is User {  return (    typeof value === 'object' &&    value !== null &&    'id' in value &&    typeof (value as any).id === 'string' &&    'email' in value &&    typeof (value as any).email === 'string' &&    'role' in value &&    ['admin', 'user'].includes((value as any).role)  );}
// ============================================================================// Error Types// ============================================================================
export interface ApiError {  status: number;  error: string;  detail?: string;}
export function isApiError(value: unknown): value is ApiError {  return (    typeof value === 'object' &&    value !== null &&    'status' in value &&    typeof (value as any).status === 'number' &&    'error' in value &&    typeof (value as any).error === 'string'  );}

Common Errors

ErrorAction
OpenAPI version != 3.0.xReport that only 3.0 is supported
$ref not foundList missing refs
Unknown typeUse unknown and warn
Circular referenceUse type alias with lazy reference

來源與署名

來源：softaworks/agent-toolkit位於skills/openapi-to-typescript提交3027f20

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 softaworks/agent-toolkit 的技能

C4 Architecture

softaworks

使用 Mermaid 圖表產生 C4 模型架構文件。

Software Development2.5K7 個月前更新

Writing Clearly And Concisely

softaworks

套用 Strunk《風格的要素》規則與 AI 寫作模式清單，讓給人閱讀的文字更清晰、更精簡。

Writing & Content2.5K7 個月前更新

Web To Markdown

softaworks

使用本機安裝的 web2md 命令列工具（Puppeteer 與 Readability）將網頁 URL 轉換為乾淨的 Markdown。

Productivity & Workflow2.5K7 個月前更新

Skill Judge

softaworks

依據官方規範與最佳實務評估 Agent Skill 的設計品質，提供多維度評分與改進建議。

AI & Agents2.5K7 個月前更新

Ship Learn Next

softaworks

把課程、文章等學習內容轉換成 Ship-Learn-Next 行動計畫，包含可交付的每週迭代。

Learning & Education2.5K7 個月前更新

Reducing Entropy

softaworks

引導代理以刪除為優先，透過衡量最終程式碼量來最小化程式碼庫總規模。

Software Development2.5K7 個月前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新