s03-08-openapi-doc
/s03-08-openapi-doc
Składa kontrakty API w pełną specyfikację OpenAPI 3.x i czytelną dokumentację, na przykład w formie pliku openapi.yaml i dokumentu.
- Autor
- yanggepeng ↗
- Repozytorium
- commercial-multiagent-sdlc ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 01.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 01.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Składa kontrakty API w pełną specyfikację OpenAPI 3.x i czytelną dokumentację, na przykład w formie pliku openapi.yaml i dokumentu.
Wyzwalacze z opisu
Argumenty
/s03-08-openapi-doc [project_id] [版本]
Oryginalny opis (EN)
把接口契约汇总为完整 OpenAPI 3.x 规范文档并生成可读文档。当用户要求'出 API 文档/Swagger/接口文档 docx'时使用。产出 openapi.yaml + 接口文档 docx。
Jak działa
- 0. 契约卡(CONTRACT)
- 1. 调用方式
- 2. 前置条件(未满足即停手回报,不得带病执行)
- 3. 输入
- 4. 执行步骤
- 5. 输出契约(精确路径)
- 6. 治理汇报协议(★ 强制)
- 7. 必须真实执行的验证命令
- 8. 完成判据(DoD)
- 9. 交付前自检
Podgląd SKILL.md
---
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` 校验,由负责人决定下一步
Wersje
W bazie nie ma innych skilli o nazwie s03-08-openapi-doc.
Migawka bazy z 13.11.2026 · wersja paczki 130b264a9de1 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100api-doc-gen
Skanuje definicje tras w kodzie Flask, FastAPI, Express lub Gin i generuje dokumentację API zgodną z OpenAPI 3.0 i Swagger. - 95api-documentation-generator
Generuje specyfikacje OpenAPI i Swagger oraz dokumentację API z kodu albo projektu. - 100openapi-expert
Wspiera projektowanie API, dokumentację i generowanie kodu ze specyfikacji OpenAPI i Swagger, w tym webhooki i polimorfizm. - 100generating-tests-from-openapi
Generuje skrypty testów obciążeniowych k6 ze specyfikacji OpenAPI 3.0 lub 3.1 w formacie YAML albo JSON. - 100openapi-to-zod
Generuje schematy Zod v4 w TypeScript z definicji OpenAPI zapisanych w openapi.yaml lub openapi.json, gdy gotowe pakiety nie obsługują Zod v4. - 100api-docs
Pisze dokumentację referencyjną lub specyfikację OpenAPI API na podstawie kodu źródłowego, np. listę endpointów i trasy.