Materal Framework Enum Adapter

Detects Materal Framework's enum endpoints and fetches real enum data from the API for efficient enum generation.

How It Works

Two-command workflow for fast, batch-style enum generation:

fetch - Get enum data from API

1. Parse OpenAPI spec for Enums/GetAll* endpoints (auto-detects namespace)
2. Extract enum names from endpoint paths
3. Fetch {Key, Value} pairs from Materal API (Chinese values)
4. Output JSON for AI batch translation

generate - Generate TypeScript files

1. Read AI-translated enum data (with English names)
2. Validate data structure
3. Generate TypeScript enum files (one per enum, overwrites existing)
4. Note: Does NOT generate index.ts - already exists from generate-ts-models

Namespace Detection

Auto-detects namespace prefix from first enum endpoint:

Endpoint Pattern	Detected Namespace	API URL Example
/MainAPI/Enums/GetAllRole	/MainAPI	{base-url}/MainAPI/Enums/GetAllRole
/GatewayAPI/Enums/GetAllStatus	/GatewayAPI	{base-url}/GatewayAPI/Enums/GetAllStatus
/Enums/GetAllType	(empty)	{base-url}/Enums/GetAllType

Usage

Fetch enum data from API

node skills/materal-enum-adapter/scripts/adapter.js <spec-file> --base-url <url> fetch

Arguments:

• spec-file - Path to OpenAPI JSON
• --base-url - Materal API base URL

Example:

node skills/materal-enum-adapter/scripts/adapter.js openapi.json --base-url http://localhost:5000 fetch

Generate TypeScript files

node skills/materal-enum-adapter/scripts/adapter.js <translation-file> [--output-dir <dir>] generate

Arguments:

• translation-file - Path to AI-translated JSON file
• --output-dir <dir> - Output directory (default: ./src/enums)

Example:

node skills/materal-enum-adapter/scripts/adapter.js translations.json --output-dir ./src/types generate

Output Format

fetch output (for AI translation)

{
  "success": true,
  "detected": true,
  "enums": ["Role", "Status"],
  "enumsSkipped": 0,
  "enumData": [
    {
      "name": "Role",
      "description": "角色",
      "values": [
        {"key": 0, "value": "管理员"},
        {"key": 1, "value": "用户"}
      ]
    }
  ]
}

Fields:

• success - Operation completed successfully
• detected - Materal Framework enum controller found
• enums - Successfully fetched enum names
• enumsSkipped - Number of failed fetches
• enumData[].name - Enum name (PascalCase)
• enumData[].description - Enum description
• enumData[].values[].key - Enum key (number or string)
• enumData[].values[].value - Original Chinese value

generate input (AI creates this)

Transform fetch output by replacing value with englishName:

{
  "enumData": [
    {
      "name": "Role",
      "values": [
        {"key": 0, "englishName": "Administrator", "originalValue": "管理员"},
        {"key": 1, "englishName": "User", "originalValue": "用户"}
      ]
    }
  ]
}

Required fields:

• enumData[].name - Enum name (PascalCase)
• enumData[].values[].key - Enum key (number or string)
• enumData[].values[].englishName - English name (PascalCase)
• enumData[].values[].originalValue - Original Chinese value (optional)

generate output (summary)

{
  "success": true,
  "generated": 2,
  "enums": ["Role", "Status"],
  "outputDir": "./src/enums"
}

Generated files:

src/enums/
├── Role.ts
└── Status.ts

Role.ts:

export enum Role {
  Administrator = 0,
  User = 1
}

Note: index.ts is NOT generated - it already exists from generate-ts-models workflow. This skill only overwrites individual enum files with translated values.

Important: Ensure --output-dir matches the directory used by generate-ts-models (default: ./types).

Workflow Example

# Step 1: Generate base models (includes enums + index.ts)
node skills/generate-ts-models/scripts/generate.js openapi.json ./src/types

# Step 2: Fetch real enum values from API
node skills/materal-enum-adapter/scripts/adapter.js openapi.json --base-url http://localhost:5000 fetch > raw.json

# Step 3: AI translates values (batch - single API call)
# Creates translations.json with englishName field

# Step 4: Generate translated enum files (overwrites only enum files)
node skills/materal-enum-adapter/scripts/adapter.js translations.json --output-dir ./src/types generate

Final output:

src/types/
├── User.ts              # from generate-ts-models
├── Role.ts              # from generate-ts-models, overwritten by materal-enum-adapter
├── index.ts             # from generate-ts-models (not regenerated)

Performance: 10-50x faster than AI generating files individually (single translation batch + instant file generation).

Requirements

• OpenAPI spec with Enums/GetAll* endpoints (any namespace prefix)
• Materal API running at --base-url
• Network access to API

Error Handling

Common errors

Command	Error	Cause	Action
fetch	Cannot read spec file	Invalid JSON or wrong path	Check file path and JSON validity
fetch	No Materal Framework Enums controller detected	No enum endpoints in spec	Verify spec format
fetch	Failed to fetch Role enum after 3 retries	API unreachable	Check API availability and network
generate	Failed to read or parse translation file	Invalid JSON	Check file path and JSON validity
generate	Invalid translation data: missing or invalid enumData array	Missing enumData	Verify JSON structure
generate	Invalid value in Role: missing key or englishName	Missing required fields	Check all values have key and englishName

Error codes: All errors exit with code 1.