Przejdź do treści
Biblioteka skilli
Programowanie · Konwersja i formaty

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.

Licencja
MIT
Ostatnia zmiana repozytorium
01.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

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

Argumenty

/s03-08-openapi-doc [project_id] [版本]
Oryginalny opis (EN)

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

Jak działa

  1. 0. 契约卡(CONTRACT)
  2. 1. 调用方式
  3. 2. 前置条件(未满足即停手回报,不得带病执行)
  4. 3. 输入
  5. 4. 执行步骤
  6. 5. 输出契约(精确路径)
  7. 6. 治理汇报协议(★ 强制)
  8. 7. 必须真实执行的验证命令
  9. 8. 完成判据(DoD)
  10. 9. 交付前自检
Sekcje z nagłówków SKILL.md, w oryginale · 177 linii, 495 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.