從 API 文件建立 API SOP

osop_version: "1.0"
id: "osop-create-api-sop"
name:"從 API 文件建立 API SOP"
description:"將現有 API 文件轉換為視覺化 SOP 工作流程。撰寫 Markdown SOP、轉換為 .osop 格式、驗證，並發布至 SOP Doc。"
tags: [osop, sop-doc, api, convert, meta]

nodes:
  - id: "gather_api_docs"
    type: "human"
    name: "收集 API 文件"
    description: "彙整 API 端點、方法、必填欄位與預期回應。來源可為 Swagger/OpenAPI 規格、內部 Wiki 或開發者知識庫。"

  - id: "write_markdown_sop"
    type: "human"
    name: "撰寫 Markdown SOP"
    description: "針對每個操作（例如「建立付款」、「提交訂單」），撰寫逐步 API 呼叫序列，包含：步驟編號、HTTP 方法、端點、請求欄位與預期回應。"

  - id: "convert_to_osop"
    type: "cli"
    name: "轉換為 .osop 檔案"
    description: "執行轉換腳本。每個 SOP 會產生一個 .osop.yaml 檔案，包含 api 節點、執行期設定（方法、URL、標頭、請求體）及循序/條件邊。"
    runtime:
      command: "python scripts/convert-sops.py API_SOP.md --output osop-examples/my-product/"

  - id: "validate_all"
    type: "cli"
    name: "osop validate（全部檔案）"
    description: "依據 JSON Schema 驗證所有產生的 .osop 檔案，並修正所有錯誤。"
    runtime:
      command: "osop validate osop-examples/my-product/*.osop.yaml"

  - id: "generate_website_data"
    type: "cli"
    name: "產生網站資料"
    description: "執行資料產生腳本，為網站圖庫產生 TypeScript 資料檔案。"
    runtime:
      command: "python scripts/generate-workflow-data.py"

  - id: "browse_sop_doc"
    type: "mcp"
    name: "在 SOP Doc 中瀏覽"
    description: "開啟 osop.ai/sop-doc，篩選「API SOP」，即可看到每個含視覺化/YAML 分頁的 SOP，並與團隊共用。"

edges:
  - from: "gather_api_docs"
    to: "write_markdown_sop"
    mode: "sequential"
  - from: "write_markdown_sop"
    to: "convert_to_osop"
    mode: "sequential"
  - from: "convert_to_osop"
    to: "validate_all"
    mode: "sequential"
  - from: "validate_all"
    to: "convert_to_osop"
    mode: "fallback"
    label: "Fix validation errors"
  - from: "validate_all"
    to: "generate_website_data"
    mode: "sequential"
  - from: "generate_website_data"
    to: "browse_sop_doc"
    mode: "sequential"