AgentSkillsCN

schema-to-openapi

将 Synnovator 数据模式转换为 OpenAPI 3.0 规范。适用于以下场景：(1) 需要根据 Synnovator 的内容类型与关联关系生成 REST API 规范；(2) 为 api-builder 技能准备输入，以便快速搭建后端代码；(3) 希望基于 Synnovator 数据模型，打造标准化、符合 RESTful 风格的 API 设计。 触发词包括：“生成 OpenAPI”“创建 API 规范”“将模式转换为 OpenAPI”“为 api-builder 做准备”“从 Synnovator 生成 REST API”。

SKILL.md
--- frontmatter
name: schema-to-openapi
description: |
  Convert Synnovator data schema to OpenAPI 3.0 specification. Use when:
  (1) Need to generate REST API spec from Synnovator's content types and relations
  (2) Preparing input for api-builder skill to scaffold backend code
  (3) Want standardized, RESTful API design from the Synnovator data model

  Triggers: "generate openapi", "create api spec", "convert schema to openapi",
  "prepare for api-builder", "generate REST API from synnovator"

Schema to OpenAPI

Generate OpenAPI 3.0 specification from Synnovator's data schema.

Quick Start

bash
uv run python .claude/skills/schema-to-openapi/scripts/generate_openapi.py

Output: .synnovator/openapi.yaml

Options

FlagDefaultDescription
--output, -o.synnovator/openapi.yamlOutput file path
--titleSynnovator APIAPI title
--version1.0.0API version
--formatyamlOutput format (yaml or json)

What Gets Generated

Content Type Endpoints (7 resources)

  • •/categories - Activity/competition management
  • •/posts - User posts and submissions
  • •/resources - File attachments
  • •/rules - Category rules and scoring criteria
  • •/users - User management
  • •/groups - Teams and groups
  • •/users/me - Current user profile

Nested Relation Endpoints

  • •/categories/{id}/rules - Category rules
  • •/categories/{id}/posts - Category submissions
  • •/categories/{id}/groups - Registered teams
  • •/groups/{id}/members - Group membership
  • •/posts/{id}/resources - Post attachments
  • •/posts/{id}/related - Related posts

Interaction Endpoints (RESTful style)

  • •POST/DELETE /posts/{id}/like - Like/unlike
  • •GET/POST /posts/{id}/comments - Comments
  • •GET/POST /posts/{id}/ratings - Ratings

Admin Batch Operations

  • •DELETE /admin/posts - Batch delete
  • •PATCH /admin/posts/status - Batch status update
  • •PATCH /admin/users/role - Batch role update

Schema Normalization

Original (engine.py)OpenAPI Spec
_body internal fieldcontent field
deleted_at exposedHidden, use ?include_deleted=true
Cache fieldsMarked readOnly: true
Scattered enumsCentralized in components/schemas

Integration with api-builder

After generating the spec:

bash
# Generate OpenAPI spec
uv run python .claude/skills/schema-to-openapi/scripts/generate_openapi.py

# Use api-builder to scaffold backend
/api-builder .synnovator/openapi.yaml

Authentication

The generated spec uses OAuth2 with three scopes:

  • •read - Read access to resources
  • •write - Write access to resources
  • •admin - Admin batch operations