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周前更新