api-schema-inferrer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Schema Inferrer

API Schema 推断器

This skill automatically generates schemas from examples in OpenAPI Specification (OAS) files. It analyzes

example

and

examples

fields in requests and responses, then produces corresponding

schema

definitions.

此 skill 会自动根据 OpenAPI Specification (OAS) 文件中的示例生成 schema。它分析请求和响应中的

example

和

examples

字段，然后生成相应的

schema

定义。

When to Use This Skill

何时使用此 Skill

Use this skill when:

Endpoints have
```
examples
```
or
```
example
```
fields but no
```
schema
```
defined
You want to quickly bootstrap schemas from sample data
Converting from formats that don't require explicit schemas

在以下情况下使用此 skill：

端点包含
```
examples
```
或
```
example
```
字段，但没有定义
```
schema
```
你想根据样本数据快速搭建 schema 骨架
从不要求显式 schema 的格式进行转换

Prerequisites

前置条件

bash

pip install pyyaml

bash

pip install pyyaml

Running Schema Inference

运行 Schema 推断

Preview Changes (Dry Run)

预览更改（Dry Run）

bash

python3 skills/api-schema-inferrer/scripts/infer_schemas.py path/to/spec.yaml --dry-run

This shows what schemas would be added without modifying the file.

bash

python3 skills/api-schema-inferrer/scripts/infer_schemas.py path/to/spec.yaml --dry-run

这会显示将添加哪些 schema，但不会修改文件。

Apply Changes

应用更改

bash

python3 skills/api-schema-inferrer/scripts/infer_schemas.py path/to/spec.yaml

This will:

Create a backup file (
```
spec.yaml.backup
```
)
Relocate any
```
example
```
nested inside a
```
schema:
```
block up to the media-type level (the OAS-canonical sibling location)
Infer schemas from all examples in requests and responses, including shared bodies under
```
components.requestBodies
```
and
```
components.responses
```
Add schemas where they are missing
Preserve existing schemas (never overwrites)

bash

python3 skills/api-schema-inferrer/scripts/infer_schemas.py path/to/spec.yaml

这将会：

创建一个备份文件（
```
spec.yaml.backup
```
）
将嵌套在
```
schema:
```
块内的任何
```
example
```
重新定位到 media type 层级（OAS 标准规定的同级位置）
根据请求和响应中的所有示例推断 schema，包括
```
components.requestBodies
```
和
```
components.responses
```
下的共享 body
在缺少 schema 的位置添加 schema
保留现有 schema（绝不覆盖）

Why the relocation pre-step matters

为什么需要先执行重新定位步骤

Some toolchains (notably AMF) emit specs where

example

is nested inside

schema:

yaml

content:
  application/json:
    schema:
      example:
        foo: bar

OAS 3.x defines

example

as a sibling of

schema

at the Media Type Object level. Tooling that follows the spec (including the portal generator in this repo) won't render schema-nested examples. The script automatically moves them so both the inferrer and downstream tooling can find them.

某些工具链（尤其是 AMF）生成的规范会将

example

嵌套在

schema:

内部：

yaml

content:
  application/json:
    schema:
      example:
        foo: bar

OAS 3.x 规定

example

应在 Media Type Object 层级作为

schema

的同级项。遵循规范的工具（包括本仓库中的门户生成器）不会渲染嵌套在 schema 中的示例。脚本会自动移动这些示例，使推断器和下游工具都能找到它们。

What It Does

功能说明

The tool:

Detects types: Automatically determines
```
string
```
,
```
number
```
,
```
integer
```
,
```
boolean
```
,
```
array
```
,
```
object
```
,
```
null
```
Handles nested objects: Recursively processes complex structures
Infers formats: Detects
```
email
```
,
```
uri
```
,
```
date
```
formats from string patterns
Sets required fields: Marks all fields as required (conservative approach)
Adds descriptions: Includes placeholder descriptions that need to be updated

该工具可以：

检测类型：自动判断
```
string
```
、
```
number
```
、
```
integer
```
、
```
boolean
```
、
```
array
```
、
```
object
```
、
```
null
```
处理嵌套对象：递归处理复杂结构
推断格式：根据字符串模式检测
```
email
```
、
```
uri
```
、
```
date
```
格式
设置必填字段：将所有字段标记为必填（保守做法）
添加描述：生成需要更新的占位描述

Example

示例

Before:

yaml

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            examples:
              createUser:
                value:
                  name: "John Doe"
                  email: "john@example.com"
                  age: 30
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                id: "123"
                status: "active"

After running inference:

yaml

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, email, age]
              properties:
                name:
                  type: string
                  description: "Auto-generated from example. TODO: Add meaningful description for 'name'"
                email:
                  type: string
                  format: email
                  description: "Auto-generated from example. TODO: Add meaningful description for 'email'"
                age:
                  type: integer
                  description: "Auto-generated from example. TODO: Add meaningful description for 'age'"
            examples:
              createUser:
                value:
                  name: "John Doe"
                  email: "john@example.com"
                  age: 30
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required: [id, status]
                properties:
                  id:
                    type: string
                    description: "Auto-generated from example. TODO: Add meaningful description for 'id'"
                  status:
                    type: string
                    description: "Auto-generated from example. TODO: Add meaningful description for 'status'"
              example:
                id: "123"
                status: "active"

推断前：

yaml

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            examples:
              createUser:
                value:
                  name: "John Doe"
                  email: "john@example.com"
                  age: 30
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                id: "123"
                status: "active"

运行推断后：

yaml

paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, email, age]
              properties:
                name:
                  type: string
                  description: "Auto-generated from example. TODO: Add meaningful description for 'name'"
                email:
                  type: string
                  format: email
                  description: "Auto-generated from example. TODO: Add meaningful description for 'email'"
                age:
                  type: integer
                  description: "Auto-generated from example. TODO: Add meaningful description for 'age'"
            examples:
              createUser:
                value:
                  name: "John Doe"
                  email: "john@example.com"
                  age: 30
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required: [id, status]
                properties:
                  id:
                    type: string
                    description: "Auto-generated from example. TODO: Add meaningful description for 'id'"
                  status:
                    type: string
                    description: "Auto-generated from example. TODO: Add meaningful description for 'status'"
              example:
                id: "123"
                status: "active"

Post-Inference Steps

推断后的步骤

After running the inference tool:

Review generated schemas: Check that inferred types are correct
Update descriptions: Replace all "TODO" placeholders with meaningful descriptions
Add enums: If a field has limited options, add an
```
enum
```
array
Refine required fields: Adjust the
```
required
```
array if some fields are optional
Add constraints: Add
```
minLength
```
,
```
maxLength
```
,
```
minimum
```
,
```
maximum
```
, etc. as needed
Run validation: Use the api-spec-validator skill to check for remaining issues

运行推断工具后：

检查生成的 schema：确认推断出的类型是否正确
更新描述：将所有 "TODO" 占位内容替换为有意义的描述
添加枚举：如果字段的选项有限，添加
```
enum
```
数组
优化必填字段：如果某些字段为可选字段，则调整
```
required
```
数组
添加约束：根据需要添加
```
minLength
```
、
```
maxLength
```
、
```
minimum
```
、
```
maximum
```
等约束
运行验证：使用 api-spec-validator skill 检查剩余问题

Using with Claude

与 Claude 配合使用

Ask Claude to infer schemas:

"Infer schemas from examples in my API spec at path/to/spec.yaml"
"Generate schemas from the examples in specs/my-api.yaml"
"My spec has examples but no schemas - can you add them?"

让 Claude 推断 schema：

"Infer schemas from examples in my API spec at path/to/spec.yaml"
"Generate schemas from the examples in specs/my-api.yaml"
"My spec has examples but no schemas - can you add them?"

api-schema-inferrer

Original

Translation

API Schema Inferrer

API Schema 推断器

When to Use This Skill

何时使用此 Skill

Prerequisites

前置条件

Running Schema Inference

运行 Schema 推断

Preview Changes (Dry Run)

预览更改（Dry Run）

Apply Changes

应用更改

Why the relocation pre-step matters

为什么需要先执行重新定位步骤

What It Does

功能说明

Example

示例

Post-Inference Steps

推断后的步骤

Using with Claude

与 Claude 配合使用

Related Skills

相关 Skill