Skip to content
Skills Library
Programming · Conversion & formats

s03-08-openapi-doc

/s03-08-openapi-doc

把接口契约汇总为完整 OpenAPI 3.x 规范文档并生成可读文档。当用户要求'出 API 文档/Swagger/接口文档 docx'时使用。产出 openapi.yaml + 接口文档 docx。

Licence
MIT
Last repository change
01.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

把接口契约汇总为完整 OpenAPI 3.x 规范文档并生成可读文档。当用户要求'出 API 文档/Swagger/接口文档 docx'时使用。产出 openapi.yaml + 接口文档 docx。

Triggers from the description

出 API 文档/Swagger/接口文档 docx

Arguments

/s03-08-openapi-doc [project_id] [版本]
Original author description

把接口契约汇总为完整 OpenAPI 3.x 规范文档并生成可读文档。当用户要求'出 API 文档/Swagger/接口文档 docx'时使用。产出 openapi.yaml + 接口文档 docx。

How it works

  1. 0. 契约卡(CONTRACT)
  2. 1. 调用方式
  3. 2. 前置条件(未满足即停手回报,不得带病执行)
  4. 3. 输入
  5. 4. 执行步骤
  6. 5. 输出契约(精确路径)
  7. 6. 治理汇报协议(★ 强制)
  8. 7. 必须真实执行的验证命令
  9. 8. 完成判据(DoD)
  10. 9. 交付前自检
Original SKILL.md headings · 177 lines, 495 words
SKILL.md preview
---
name: "s03-08-openapi-doc"
description: "把接口契约汇总为完整 OpenAPI 3.x 规范文档并生成可读文档。当用户要求'出 API 文档/Swagger/接口文档 docx'时使用。产出 openapi.yaml + 接口文档 docx。"
allowed-tools: "Read, Write, Bash(python:*)"
argument-hint: "[project_id] [版本]"
---

# OpenAPI文档 `S03-08-openapi-doc`

> 分组:S03 产品技术设计 | 主责阶段:STAGE_3 | 负责角色:`product-designer`

**职责边界**:只做设计:架构选型/模块拆分/实体建模/ER/表设计/接口/权限/小程序能力。冻结后成为开发契约。

## 0. 契约卡(CONTRACT)

| 契约项 | 值 |
|---|---|
| 技能ID | `S03-08-openapi-doc` |
| 分组 | S03 产品技术设计 |
| 主责阶段 | STAGE_3 |
| 负责角色 | `product-designer` |
| 产物根目录 | `artifacts/stage3-design` |
| 前置门禁 | `G1_input_ready`、`G2_channel_check`、`G3_oss_and_baseline` |
| 允许写入 | `artifacts/stage3-design` 及本技能「输出契约」列出的路径 |
| 禁止触碰 | `state/**`、`baseline/**`(受 protect_state 钩子硬拦截) |
| 越权后果 | 不在 RTM/基线内的需求 = 超范围,须 `scope check` 后走变更单 |

> 契约卡随技能一起注入,**不依赖对话记忆**。若与对话中说法冲突,以本卡为准。

## 1. 调用方式

```bash
/commercial-multiagent-sdlc:s03-08-openapi-doc [project_id] [版本]
用 S03-08-openapi-doc 这个技能做OpenAPI文档
```

## 2. 前置条件(未满足即停手回报,不得带病执行)

- 接口清单已完成

门禁硬校验(引擎执行,模型无法绕过):

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G1_input_ready
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G2_channel_check
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G3_oss_and_baseline
```

## 3. 输入

- artifacts/stage3-design/openapi/*.yaml
- artifacts/stage3-design/接口清单

## 4. 执行步骤

1. 汇总所有片段为单份 openapi.yaml,补全 info / servers / securitySchemes
2. 所有 schema 必须有 description 与 example
3. 校验文档可被标准工具解析(字段无越界引用)
4. 生成人类可读的接口说明 docx,按模块分组
5. 标注废弃接口与兼容性说明

**命名规范**:`PJ-<项目号>-<技术方案|数据库设计|接口清单>-v<版本>.docx|openapi/api.yaml`

## 5. 输出契约(精确路径)

- artifacts/stage3-design/openapi.yaml
- artifacts/stage3-design/PJ-xxx-接口文档-v1.0.docx
- 返回:路径数 / schema 数

## 6. 治理汇报协议(★ 强制)

本技能**必须**向管控体系回报,禁止闷头干完不吭声。回报由 `scripts/governance.py` 承载,回报记录落到 `state/skill-runs.yaml`,Lead 看板可读。

**① 开工登记(第一步就做,未登记视为黑工)**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill start --skill S03-08-openapi-doc \
    --f <覆盖的F-xx,逗号分隔> --task "<本次任务一句话>" \
    --worker <worker-id,并行开发时必填>
# 成功输出 RUN-xxx;未过门禁会 exit 2 并给出缺哪个门禁
```

**② 定时回报进度(执行过程中,不得只在结束时报一次)**

> 回报频率:每完成 1 个设计文档回报一次

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill progress --run RUN-xxx --pct 40 --note "<已完成什么>"
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill beat    --run RUN-xxx          # 纯心跳,不改百分比
```

**③ 完成汇报结果(收尾必做)**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" skill done --run RUN-xxx --status success \
    --summary "<结果摘要>" \
    --files "<产出路径,逗号分隔>" \
    --blockers "<阻塞点,没有就省略>"
# status 可选 success / partial / blocked / failed(引擎统一接受)
# 非 success 必须给 --summary 说明原因,否则 exit 2
```

**④ 汇报后由负责人决定下一步**


汇报完成后,**技能的执行者不得自行决定下一步**。流程为:

```
技能 done ──▶ 管控体系记录结果与产出
             ──▶ Lead 汇总进看板(governance.py skill board)
             ──▶ 负责人(用户 / Lead)判定:
                  ├─ 通过     → 回填 RTM → 推进下一技能或下一阶段
                  ├─ 需返工   → 指定同一或另一 worker 重跑,保留原 RUN 记录
                  ├─ 需变更   → 走 g-change 变更单,重走受影响门禁
                  └─ 已阻塞   → 登记 blocker,升级给用户决策
```

纪律:
- 终态任务**不得**再报进度或重复提交结果(引擎会 exit 1 拒绝)
- 心跳超时由 `skill_heartbeat.py` 钩子在 Stop/PostToolUse 时告警
- 未 `skill start` 就产出文件 = 黑工,Lead 复盘时按违规计

## 7. 必须真实执行的验证命令

**开工前必跑(任一非零退出即停手回报,不得带病执行)**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" status
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G1_input_ready
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G2_channel_check
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" gate check G3_oss_and_baseline
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" baseline verify
```

**本技能专项验证**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/export.py" --input artifacts/stage3-design/接口文档.draft.md --to docx
```

**完工后必跑**

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" status
python "${CLAUDE_PLUGIN_ROOT}/scripts/governance.py" rtm coverage --stage design
```

> 验证命令必须真实运行并把结果回报给用户;只「在脑子里过一遍」视为未执行。

## 8. 完成判据(DoD)

- 每个 F-xx 都能在 RTM「设计产物」列查到具体文件(未映射数 = 0)
- 接口清单每条含:路径/方法/入参/出参/错误码/权限点,六项缺一即不合格
- 表设计每张含:字段/类型/非空/默认值/索引/注释,且实体与表一一对应
- 每个第三方依赖在 oss-review.yaml 中都有 license + verdict 两列
- 接口契约已由 `contract freeze` 冻结(state/contract.lock 存在);G4 确签由用户在阶段出口执行

## 9. 交付前自检

- [ ] 文档可被解析无悬空引用
- [ ] 每个 schema 有 example
- [ ] 安全方案已定义

## 10. 反例与常见错误(踩过的坑,勿重蹈)

- 设计与 RTM 脱节 —— 设计完必须回填 RTM,否则阶段5核验必然挂
- 接口只写成功响应不写错误码 —— 开发期会各自发挥
- 选了 GPL/AGPL 基座还做商用闭源 —— 许可证合规一票否决
- G4 自己签 —— 确签人必须是用户,Lead 自签返回 exit 2
- 表设计没有索引与约束 —— 上线后性能与数据一致性问题会集中爆发

---

### 铁律(执行本技能期间必须遵守)

1. 前置条件未满足即刻停止并回报,**不得带病执行**
2. 先 `skill start` 登记再动手;过程中定时 `skill progress`;完工 `skill done`
3. 只操作归属于本角色/本 worker 的文件,跨模块改动一律先走 `/g-change`
4. 产物先写 `.draft.md`;对外正式件必须由 `scripts/export.py` 导出 docx/pdf/xlsx,**Markdown 只能作内部草案或台账,不得作为对外交付件**
5. 输出超出需求基线的内容 = 超范围,先 `scope check`,拦截并回到 Lead
6. 门禁确签只能由用户执行(Lead 自签返回 exit 2),第三方审计只能由 change-auditor 执行
7. 本技能执行完毕即收尾:`skill done` 回报 + `/g-status` 校验,由负责人决定下一步

Versions

The database has no other skills named s03-08-openapi-doc.

Database snapshot: 13.11.2026 · package version 130b264a9de1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100api-doc-gen
    从 Flask、FastAPI、Express 或 Gin 等 Web 框架的源代码中自动扫描路由定义,生成符合 OpenAPI 3.0 / Swagger 规范的标准化 API 文档文件。当用户需要生成 API 文档、提到 OpenAPI、Swagger、接口文档、路由扫描或从代码自动提取接口信息时触发。
  • 95api-documentation-generator
    Generate OpenAPI/Swagger specifications and API documentation from code or design. Use when creating API docs, generating OpenAPI specs, or documenting REST APIs.
  • 100openapi-expert
    Expert-level OpenAPI/Swagger specification for API design, documentation, and code generation. Use when the user mentions swagger, API specs, REST, API design, or documentation, or when the task involves OpenAPI Specification, Webhooks, or Polymorphism.
  • 100generating-tests-from-openapi
    Use when generating k6 load test scripts from OpenAPI specification files (YAML or JSON). Use when the user has an OpenAPI spec, API specification, or wants to create k6 tests from API documentation defined in OpenAPI 3.0 or 3.1 format.
  • 100openapi-to-zod
    Generate Zod v4 TypeScript schemas from OpenAPI (openapi.yaml / openapi.json) definitions. This skill exists because npm packages like openapi-zod-client do not support Zod v4 — Claude reads the YAML/JSON directly and writes the conversion. Use this skill whenever the user wants…
  • 100api-docs
    Write reference documentation or an OpenAPI spec for a REST/HTTP API by reading its source code. Use when the user says "document the API", "write endpoint docs", "generate an OpenAPI/Swagger spec", "what endpoints do we have", or "document this route".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.