Agent Skills › flexprice/flexprice › openapi

openapi

GitHub

用于生成和更新 OpenAPI 规范、SDK 及 MCP 工具的自动化流程。支持 Swagger 注释解析、多语言 SDK 生成、自定义代码合并及验证，确保 API 契约与客户端库同步。

.cursor/skills/openapi/SKILL.md flexprice/flexprice

Trigger Scenarios

修改了路由或 Swagger 注解后需要生成新的 API 规范需要同步更新生成的 SDK 或 MCP 工具定义执行 OpenAPI 规范的合法性校验

Install

npx skills add flexprice/flexprice --skill openapi -g -y

More Options

Use without installing

npx skills use flexprice/flexprice@openapi

指定 Agent (Claude Code)

npx skills add flexprice/flexprice --skill openapi -a claude-code -g -y

安装 repo 全部 skill

npx skills add flexprice/flexprice --all -g -y

预览 repo 内 skill

npx skills add flexprice/flexprice --list

SKILL.md

Frontmatter

{
    "name": "openapi",
    "description": "Swagger + Speakeasy SDK\/MCP pipeline (make swagger, sdk-all), api\/custom merge. Trigger: openapi, swagger, sdk-all, MCP."
}

`openapi` — OpenAPI & SDKs

Source of truth

Handlers: Swagger comments in internal/api/**.
Generated specs: docs/swagger/ (run generation — do not hand-edit JSON as primary source).

Standard sequence

After route or Swagger annotation changes:

make swagger
make sdk-all

make sdk-all (per AGENTS.md) validates, generates SDKs/MCP, merges api/custom/**.

OpenAPI-only validation:

make speakeasy-validate

Custom vs generated

Do not put long-lived custom logic only in generated trees under api/go, api/typescript, api/python, api/mcp.
Put custom code in api/custom/<lang>/ and rely on make merge-custom (often part of sdk-all).

MCP tooling

Filtered spec and allowed tags live under .speakeasy/mcp/ — changing exposed tools requires config update + regenerate flow documented in AGENTS.md.

When to skip full `sdk-all`

Small internal-only HTTP tweak with no exported contract change: make swagger alone may suffice; coordinate with reviewers if public SDK repos are consumers.