ความปลอดภัยเอกสาร API: สเปคของคุณปลอดภัยใน Git หรือไม่

ความปลอดภัยของเอกสาร API เป็นพื้นผิวที่ทีมมักมองข้าม คุณอาจล็อก API ด้วย authentication, rate limiting และ security testing แล้ว แต่ OpenAPI spec, Swagger UI, Markdown ที่อธิบาย auth flow หรือ docs site อาจยังอยู่ใน Git repo หรือ static host ที่ไม่มีใครตรวจสอบมานาน เหตุการณ์วันที่ 20 พฤษภาคม 2026 ที่ GitHub ยืนยันว่าผู้โจมตีขโมยข้อมูลจาก repo ภายในประมาณ 3,800 แห่งผ่าน VS Code extension ที่ติดมัลแวร์ เป็นสัญญาณให้ถามคำถามนี้กับระบบของคุณเอง: ถ้ามีคนแอบแก้เอกสาร API ที่เผยแพร่แล้ว คุณจะรู้ไหม และผู้ใช้ API ของคุณจะรู้ไหม?

ลองใช้ Apidog วันนี้

สรุปย่อ

การรักษาความปลอดภัยของเอกสาร API หมายถึงเอกสารต้องมีการควบคุมการเข้าถึง, ประวัติเวอร์ชัน, ความสมบูรณ์ที่ตรวจสอบได้ และ audit log เพื่อไม่ให้ repo หรือ host ที่ถูกบุกรุกสามารถส่ง endpoint, token หรือคำแนะนำ authentication ที่ผิดไปยังนักพัฒนาที่คัดลอกไปใช้ใน production ได้แบบเงียบๆ

Docs-as-code ใน Git ยังเป็นแนวทางที่ดีเมื่อมี branch protection, review และ pipeline ที่รัดกุม แต่จะกลายเป็นจุดอ่อนเมื่อ repo เปิดสาธารณะโดยไม่ตั้งใจ, spec ล้าสมัยจาก API จริง หรือ static docs ไม่มี access control เลเยอร์เอกสารที่จัดการโดยผู้ให้บริการ เช่น Apidog ช่วยเพิ่ม password protection, IP/email allowlist, custom domain, version management และ spec ที่ sync กับ API design เป็น source of truth

ทำไมการละเมิดข้อมูลของ GitHub ควรทำให้คุณตรวจสอบเอกสาร API

เหตุการณ์ของ GitHub ไม่ได้แปลว่าคุณต้องเลิกใช้ Git หรือ docs-as-code แต่เป็นกรณีศึกษาที่ชัดเจนว่า endpoint ของนักพัฒนาและเครื่องมือในเครื่องสามารถกลายเป็นทางเข้าถึง repo ได้ กลุ่ม TeamPCP ขโมย repo ภายในของ GitHub และพยายามขายชุดข้อมูลในฟอรัมใต้ดิน ตาม รายงานของ BleepingComputer ส่วนขยาย VS Code ที่เป็นอันตรายมาจาก marketplace ทางการและรันอยู่บนอุปกรณ์ของพนักงาน GitHub ระบุว่ายังไม่พบหลักฐานว่าข้อมูลลูกค้าที่อยู่นอก repo ภายในได้รับผลกระทบ และการสอบสวนยังดำเนินอยู่

สิ่งที่ทีม API ควรทำทันทีคือ inventory เอกสาร API ของตัวเอง:

1. เอกสาร API ถูกเผยแพร่ไว้ที่ไหนบ้าง?
2. ใครมีสิทธิ์แก้ OpenAPI spec หรือ Markdown docs?
3. CI/CD ที่ build docs ใช้ token อะไร และ scope แค่ไหน?
4. docs site มี access control จริงหรือแค่ URL ที่เดายาก?
5. มีวิธีตรวจสอบไหมว่า docs ที่ deploy อยู่ตรงกับ source ที่ review แล้ว?

เหตุผลที่คำถามเหล่านี้สำคัญ: เอกสาร API คือคำสั่งที่นักพัฒนาคัดลอกไปใช้จริง พวกเขาคัดลอก endpoint, request body, auth header และตัวอย่าง token จากเอกสารไปใส่ใน service ของตัวเอง ถ้าผู้โจมตีแก้คำแนะนำเหล่านี้ได้ พวกเขาไม่ได้แค่แก้หน้าเว็บ แต่กำลังเปลี่ยนโค้ดที่คนอื่นจะรันใน production

ตรรกะเดียวกันนี้เกิดขึ้นกับ incident อื่นๆ ด้วย เช่นบทความของเราเรื่อง บทเรียนความปลอดภัย API จากการละเมิดข้อมูลของ Vercel ที่อธิบายว่าการเปลี่ยนแปลงเล็กๆ บนพื้นผิวที่ trusted สามารถกระทบระบบปลายน้ำได้อย่างไร

บทความนี้จะโฟกัส 4 เรื่อง:

• เอกสาร API ที่ถูกบุกรุกสร้างความเสียหายได้อย่างไร
• เมื่อ docs-as-code ใน Git เหมาะสม และเมื่อกลายเป็นความเสี่ยง
• checklist สำหรับ “เอกสาร API ที่ปลอดภัย”
• วิธีใช้เลเยอร์เอกสารที่จัดการโดยผู้ให้บริการเพื่ออุดช่องว่าง

บทความที่เกี่ยวข้อง: ความหมายของการละเมิดข้อมูลของ GitHub สำหรับเครื่องมือ API ที่โฮสต์เอง และ ความปลอดภัยของคีย์ API ของส่วนขยาย VS Code

จะเกิดอะไรขึ้นเมื่อ repo หรือ host เอกสาร API ถูกบุกรุก

ให้มองเอกสาร API เป็น attack surface หนึ่งชุด:

• Git repo ที่เก็บ spec และ docs
• CI pipeline ที่ build docs
• static host หรือ docs host ที่ serve เอกสาร
• token ที่ใช้ deploy
• account ที่มีสิทธิ์แก้หรือ publish

ถ้าจุดใดจุดหนึ่งถูกบุกรุก ผลกระทบอาจไม่ใช่แค่หน้าเอกสารพัง แต่เป็นการส่งคำแนะนำผิดไปยังผู้ใช้ API

1. การแก้เอกสารอาจเปลี่ยนโค้ด production ของผู้ใช้

ตัวอย่างที่เลวร้ายที่สุดคือการแก้เล็กมากจน reviewer มองข้าม:

• เปลี่ยน https://api.payments.acme.com/v2/charge เป็นโดเมนที่ผู้โจมตีควบคุม
• เปลี่ยน bearer token ตัวอย่างให้วิ่งผ่าน proxy ของผู้โจมตี
• เปลี่ยน OAuth token exchange URL ในประโยคเดียว
• เพิ่ม header หรือ query parameter ที่ leak credential

หน้าเว็บยัง render ได้ CI ยังผ่าน เพราะ YAML หรือ Markdown ยังถูกต้อง แต่ developer ที่ copy ตัวอย่างไปใช้จะส่ง traffic ไปผิดที่

ตัวอย่าง OpenAPI:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

ถ้าผู้โจมตีเปลี่ยนเฉพาะ servers.url ผ่าน account ที่ถูกยึด หรือผ่าน deploy host ที่ถูกยึด ผู้ใช้ที่ generate client ใหม่จาก spec จะส่งข้อมูลไปยังโดเมนผิด ความต่างอาจมีแค่ไม่กี่ตัวอักษร แต่ผลกระทบสูงมาก

สิ่งที่ควรทำ:

# ตรวจ endpoint domain ใน OpenAPI spec
grep -R "url:" ./openapi ./docs

# ตรวจ domain แปลกใน Markdown docs
grep -R "https://" ./docs | grep -v "yourcompany.com"

ใน CI ควรเพิ่ม rule ตรวจว่า server URL อยู่ใน allowlist:

const fs = require("fs");
const yaml = require("js-yaml");

const spec = yaml.load(fs.readFileSync("./openapi.yaml", "utf8"));
const allowedHosts = new Set(["api.acme-pay.com", "sandbox.acme-pay.com"]);

for (const server of spec.servers || []) {
  const host = new URL(server.url).host;
  if (!allowedHosts.has(host)) {
    throw new Error(`Unexpected OpenAPI server host: ${host}`);
  }
}

2. ปลายทางภายในและปลายทางที่ไม่ได้ตั้งใจเผยแพร่อาจรั่ว

repo เอกสารมักสะสมสิ่งที่ไม่ควรอยู่ public:

• admin endpoint
• internal-only endpoint
• debug route
• partner-only operation
• schema ของ payload ภายใน
• error code ที่เผย implementation detail

ถ้า repo public โดยไม่ตั้งใจ หรือ repo private ถูกขโมย ผู้โจมตีจะได้แผนที่ API แบบละเอียด ไม่ต้องเดา path หรือ parameter เอง

ตัวอย่าง pattern ที่ควร scan:

grep -R "/admin\|/internal\|/debug\|x-internal" ./openapi ./docs

ถ้าคุณต้องการ framework สำหรับตรวจพื้นผิวเหล่านี้ก่อนผู้โจมตี ดู รายการตรวจสอบการทดสอบความปลอดภัย API สำหรับปี 2026

3. GitHub Pages สาธารณะไม่มี access control

GitHub Pages เป็น static host ที่ serve ไฟล์ มันไม่ได้รู้ว่าใครกำลังอ่านไฟล์นั้น สำหรับ API สาธารณะ 100% นี่ไม่ใช่ปัญหา แต่ถ้า docs ควรเปิดให้เฉพาะลูกค้าที่จ่ายเงิน, partner หรือทีมภายใน GitHub Pages แบบ public ไม่ใช่เครื่องมือที่เหมาะ

หลายทีมแก้ด้วย “URL ที่เดายาก” เช่น path ยาวๆ ที่ไม่มีใคร link ถึง แต่นั่นไม่ใช่ access control เพราะ URL รั่วได้ผ่าน:

• browser history
• referrer header
• proxy log
• shared bookmark
• screenshot
• chat history

ถ้าคุณเพิกถอนสิทธิ์ของคนหนึ่งคนไม่ได้ภายในไม่กี่นาที แปลว่าคุณยังไม่มี access control จริง

4. เอกสารที่ล้าสมัยทำให้ตรวจสอบความถูกต้องไม่ได้

แม้ไม่มีผู้โจมตี docs ก็ drift ได้ เช่น API เปลี่ยน behavior แต่ OpenAPI spec ไม่ถูกอัปเดต ผู้ใช้ integrate ตาม docs แล้วเจอ runtime behavior ที่ต่างจากเอกสาร

เมื่อเกิด incident ปัญหานี้ยิ่งแย่ เพราะคุณตอบไม่ได้ว่า:

• endpoint นี้ผิดมาตลอดหรือเพิ่งถูกแก้?
• docs ที่ deploy อยู่ตรงกับ commit ไหน?
• spec นี้มาจาก API จริงหรือเขียนมือ?
• ใคร approve การเปลี่ยนแปลงนี้?

ถ้าไม่มี source of truth และ audit trail เอกสารจะกลายเป็นสิ่งที่ตรวจสอบไม่ได้

เมื่อ docs-as-code ใน Git ดี และเมื่อเป็นจุดอ่อน

Docs-as-code เป็นแนวทางที่ดีมากเมื่อใช้อย่างมีวินัย: เก็บ OpenAPI และ Markdown ใน Git, review ผ่าน Pull Request, build Swagger UI หรือ Redoc ด้วย CI แล้ว deploy ไปยัง static host คุณจะได้ history, review และ versioning แบบเดียวกับโค้ด

คำถามจึงไม่ใช่ “ควรใช้ Git ไหม” แต่คือ “setup นี้ปลอดภัยสำหรับ API ชุดนี้หรือไม่”

Docs-as-code ใน Git เหมาะสมเมื่อ

ใช้แนวทางนี้ต่อได้ถ้าเงื่อนไขเหล่านี้เป็นจริง:

• API เป็น public จริง ไม่มี endpoint หรือ schema ที่ต้องซ่อน
• repo มี branch protection
• ต้องมี reviewer ก่อน merge
• จำกัด write access เฉพาะคนที่จำเป็น
• CI action ถูก pin version และตรวจ third-party action แล้ว
• deploy token มี scope จำกัด
• spec ถูก generate จาก API จริง หรือ validate กับ API จริง
• มี owner ชัดเจนสำหรับการอัปเดตเอกสาร

ตัวอย่าง GitHub branch protection ที่ควรเปิด:

• Require pull request before merging
• Require approvals
• Require status checks to pass
• Require conversation resolution
• Restrict who can push to matching branches
• Do not allow bypassing the above settings

ตัวอย่าง CI check พื้นฐานสำหรับ OpenAPI:

name: Validate API docs

on:
  pull_request:
    paths:
      - "openapi.yaml"
      - "docs/**"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate OpenAPI
        run: npx @redocly/cli lint openapi.yaml

ถ้าทั้งหมดนี้ทำจริง Git history คือ audit log และ Pull Request review คือ integrity gate ของคุณ

Docs-as-code ใน Git กลายเป็นจุดอ่อนเมื่อ

setup เดียวกันจะเสี่ยงเมื่อ:

• docs ควร private แต่ host ไม่มี access control
• write access กว้างเกินไป
• service account หรือ CI token ไม่มี owner
• docs PR ถูก approve ง่ายเพราะ “แค่เอกสาร”
• spec เขียนมือและ drift จาก API จริง
• repo รวม endpoint public และ internal ไว้ด้วยกัน
• ไม่มีวิธีพิสูจน์ว่า deployed site ตรงกับ reviewed source

เหตุการณ์ GitHub สอดคล้องกับ failure mode นี้: การโจมตีเริ่มจากเครื่อง developer แล้วเข้าถึง repo ภายในได้ Git ให้ transparency แต่ไม่ให้ secrecy เมื่อ repo ถูกขโมยไปแล้ว

ดูการเปรียบเทียบแนวทางโฮสต์เอกสาร API เพิ่มเติมได้ที่ การเปรียบเทียบเอกสาร API ที่โฮสต์เอง

ข้อสรุป: ใช้ docs-as-code ต่อถ้า API เป็น public และ pipeline แข็งแรง แต่ถ้า docs ต้องมี access control หรือคุณตอบไม่ได้ว่า deployed docs ตรงกับ reviewed source หรือไม่ ควรเปลี่ยน architecture

“เอกสาร API ที่ปลอดภัย” ต้องมีอะไรบ้าง

ให้ตรวจด้วย checklist 4 ข้อนี้

1. การควบคุมการเข้าถึง

เอกสารต้องมองเห็นเฉพาะคนที่ควรมองเห็น:

• public สำหรับ public API
• restricted สำหรับลูกค้า
• restricted สำหรับ partner
• internal-only สำหรับทีมภายใน

การควบคุมต้องเป็น gate จริง เช่น password, IP allowlist, email allowlist หรือ SSO ไม่ใช่ URL ที่เดายาก

คำถามตรวจสอบ:

• ตอนนี้ใครอ่าน docs ได้บ้าง?
• เพิกถอนสิทธิ์ของคนหนึ่งคนได้ภายใน 1 นาทีไหม?
• มี log หรือวิธี audit การเข้าถึงไหม?
• partner ที่หมดสัญญายังเข้า docs ได้หรือไม่?

2. การจัดการเวอร์ชัน

ผู้ใช้ API v1 ควรเห็น docs v1 ผู้ใช้ v2 ควรเห็น docs v2 คุณควรตอบได้ว่าในวันที่กำหนด docs ระบุอะไรไว้

คำถามตรวจสอบ:

• ยังเข้าถึง docs ของ API version เก่าได้ไหม?
• docs v1 ถูก overwrite ด้วย docs v2 หรือไม่?
• changelog เชื่อมกับ release ของ API หรือไม่?

3. ความสมบูรณ์

คุณต้องตรวจสอบได้ว่า docs ที่เผยแพร่ตรงกับสิ่งที่ตั้งใจ publish

คำถามตรวจสอบ:

• ถ้ามีคนเปลี่ยน endpoint URL ใน docs production เมื่อ 1 ชั่วโมงก่อน จะมี alert ไหม?
• docs มาจาก source of truth เดียวหรือแก้แยกหลายที่?
• deployed site ตรงกับ commit หรือ API design version ไหน?

4. Audit log

คุณต้องตอบได้ว่าใครเปลี่ยนอะไร เมื่อไร และ publish ไปที่ไหน

คำถามตรวจสอบ:

• สร้าง change log ย้อนหลัง 90 วันได้ไหม?
• รู้ไหมว่าใคร publish docs version ล่าสุด?
• deploy pipeline มี log แยกจาก Git history หรือไม่?

เอกสาร API ที่ปลอดภัยต้องผ่านทั้ง 4 ข้อนี้ ไม่ใช่แค่ “อยู่ใน Git” หรือ “มี HTTPS”

Apidog ให้เอกสาร API ที่ปลอดภัยได้อย่างไร

Apidog เป็นแพลตฟอร์ม API สำหรับ design, debug, test, mock และ documentation จุดสำคัญคือ docs ถูกสร้างจาก API design ในโปรเจกต์เดียวกัน แทนที่จะเป็น Markdown หรือ YAML ที่กระจายอยู่คนละที่

ถ้าต้องการลองทำตาม ให้ ดาวน์โหลด Apidog แล้วเปิดโปรเจกต์ที่มี API definition

1. เผยแพร่เอกสารจาก source of truth ที่ควบคุมได้

ใน Apidog คุณออกแบบ endpoint, schema และ authentication ใน API designer จากนั้น Apidog สร้าง เอกสารโดยอัตโนมัติ จาก definition เดียวกัน เมื่อ publish จะได้ interactive docs พร้อม “Try it” console และ code samples หลายภาษา

แนวทางนี้ลด drift เพราะ docs ไม่ได้เป็นไฟล์ Markdown ที่แก้แยกจาก API design หากต้องการเปลี่ยนสิ่งที่ผู้ใช้เห็น ต้องเปลี่ยน API definition ในโปรเจกต์ ซึ่งอยู่ภายใต้ permission และ change history ของโปรเจกต์นั้น

Workflow ที่ควรใช้:

1. Import หรือสร้าง API definition ใน Apidog
2. ตรวจ schema, auth และ environment ให้ถูกต้อง
3. Publish docs จาก API definition
4. ตั้ง visibility และ access control
5. ใช้ versioning เมื่อมี breaking change

2. ตั้ง access control สำหรับเอกสาร

เมื่อ publish docs ใน Apidog คุณเลือก visibility ได้หลายแบบ:

• สาธารณะ: ใครมีลิงก์ก็อ่านได้ เหมาะกับ public API
• Password protection: ตั้งหรือ generate password แล้วแชร์ให้ stakeholder
• IP allowlist: จำกัดเฉพาะ IP หรือ CIDR เช่น office network หรือ VPN
• Email allowlist: ระบุ email หรือ domain ที่เข้าได้ เช่น *@yourcompany.com
• Custom login: เชื่อมระบบ authentication ของคุณเอง โดย server ออก JWT แล้ว Apidog ตรวจสอบ

รายละเอียดอยู่ใน คู่มือการควบคุมการเข้าถึงเอกสาร API

ตัวอย่างการเลือกแบบใช้งานจริง:

กรณีใช้งาน	วิธีที่เหมาะ
Public API	Public docs
Docs สำหรับลูกค้าทดลอง	Password protection
Docs ภายในองค์กร	IP allowlist ผ่าน VPN
Docs สำหรับ partner หลายบริษัท	Email allowlist ตาม domain
ต้องใช้ auth ขององค์กรเอง	Custom login

3. ใช้ custom domain

คุณสามารถให้บริการ docs บน domain ของตัวเอง เช่น developer.yourcompany.com แทน URL ทั่วไป Apidog รองรับ โดเมนที่กำหนดเอง ผ่าน DNS CNAME หรือ reverse proxy

Custom domain ไม่ใช่ security control โดยตัวเอง แต่ช่วยให้ docs อยู่ภายใต้ domain ที่ผู้ใช้เชื่อถือ และทำให้ทีมจัดการ ownership ได้ชัดเจนกว่า docs ที่กระจายอยู่บน static host หลายที่

4. รักษา OpenAPI spec ให้ sync กับ API design

ความคลาดเคลื่อนของ spec เป็นปัญหาด้านความปลอดภัย เพราะทำให้ docs ตรวจสอบไม่ได้ Apidog ใช้ API design เป็น source of truth และ sync docs กับการเปลี่ยนแปลง design

Apidog รองรับการนำเข้า:

• OpenAPI 3.0
• OpenAPI 3.1
• Swagger 2.0
• scheduled import เพื่ออัปเดต spec ภายนอกตามรอบ

ถ้าปัจจุบันคุณดูแล spec ด้วยมือใน Git repo ให้เริ่มจากขั้นตอนนี้:

1. Export OpenAPI จาก repo เดิม
2. Import เข้า Apidog
3. ตรวจ servers, auth scheme, schema และ examples
4. Publish docs จาก Apidog
5. ตั้ง access control
6. เก็บ Git repo เดิมเป็น source archive หรือใช้เฉพาะ CI validation ตาม workflow ของทีม

ทีมที่ย้ายจาก SwaggerHub สามารถดู คู่มือย้ายเอกสาร API ของ SwaggerHub ไปยัง Apidog

5. จัดการเวอร์ชันเอกสาร

Apidog รองรับการ publish เอกสารหลายเวอร์ชันขนานกัน เช่น v1 และ v2 ผู้ใช้ที่ยัง integrate กับ API v1 จะยังเข้าถึง docs v1 ได้ แม้ v2 ถูกปล่อยแล้ว

แนวทางแนะนำ:

• ใช้ version แยกเมื่อมี breaking change
• เก็บ docs version เก่าไว้ตราบเท่าที่ยังมีผู้ใช้ API version นั้น
• ระบุ deprecation notice ใน docs version เก่า
• เชื่อม changelog กับ release note ของ API

คุณสมบัติเหล่านี้ไม่สามารถหยุดผู้โจมตีจากการเจาะเครื่อง developer ได้โดยตรง แต่ช่วยให้คุณตอบคำถามสำคัญได้ชัดเจน:

• ใครอ่าน docs ได้?
• docs version ไหนถูกเผยแพร่?
• docs ที่เผยแพร่ตรงกับ API design หรือไม่?
• มีอะไรเปลี่ยนไปเมื่อไร?

นั่นคือระดับการตรวจสอบที่ incident แบบ GitHub ควรกระตุ้นให้ทุกทีมทำ

เปรียบเทียบตัวเลือกการโฮสต์เอกสาร

คุณสมบัติ	GitHub Pages สาธารณะ (Swagger UI / Redoc)	เอกสารที่โฮสต์เองบนเซิร์ฟเวอร์ของคุณ	เอกสารที่จัดการโดยผู้ให้บริการ (Apidog)
การควบคุมการเข้าถึง	ไม่มี; อาศัย URL ที่คลุมเครือเท่านั้น	ขึ้นอยู่กับสิ่งที่คุณสร้างและดูแล	มีในตัว: รหัสผ่าน, IP, อีเมล, การเข้าสู่ระบบแบบกำหนดเอง
การจัดการเวอร์ชัน	ด้วยตนเอง; การสร้างหรือ branch แยกกัน	ด้วยตนเอง	มีในตัว; เผยแพร่หลายเวอร์ชันเคียงข้างกัน
ความสมบูรณ์	การตรวจสอบ Git + ประวัติ หากบังคับใช้	ขึ้นอยู่กับ pipeline ของคุณ	เอกสารที่สร้างขึ้นจากการออกแบบ API ที่ควบคุมได้
บันทึกการตรวจสอบ	ประวัติ Git สำหรับ repo, ไม่ใช่สำหรับการปรับใช้	ขึ้นอยู่กับการบันทึกของคุณ	ประวัติการเปลี่ยนแปลงในการออกแบบและเอกสารที่เผยแพร่
ค่าใช้จ่ายในการบำรุงรักษา	ตั้งค่าต่ำ, ต้องดูแล pipeline ต่อเนื่อง	สูง; ต้องดูแลทั้งระบบเอง	ต่ำ; แพลตฟอร์มดูแล hosting และ control layer
เหมาะกับ	API สาธารณะเต็มรูปแบบและ pipeline ที่มีวินัย	ทีมที่มี requirement โฮสต์เองเข้มงวด	ทีมที่ต้องการ access control โดยไม่เพิ่ม operational overhead

ไม่มีตัวเลือกที่ถูกต้องเสมอไป GitHub Pages เหมาะกับ public API ที่ pipeline ถูกล็อกดี Self-hosting เหมาะกับทีมที่มีข้อกำหนดด้าน data residency หรือ isolation เข้มงวด ส่วน managed docs เหมาะกับทีมที่ต้องการ access control, versioning และ hosting โดยไม่ต้องสร้างเองทั้งหมด

อ่านเพิ่มได้ที่ การเปรียบเทียบเอกสาร API ที่โฮสต์เอง และ การเปรียบเทียบ Scalar vs SwaggerHub vs Apidog

Checklist สำหรับนำไปใช้ทันที

ใช้รายการนี้กับ docs site ของคุณในสัปดาห์นี้:

[ ] ระบุ docs site ทั้งหมดที่ถูก publish
[ ] ระบุ repo หรือ source ที่สร้าง docs แต่ละชุด
[ ] ตรวจว่า docs ใดเป็น public, partner-only, internal-only
[ ] ตรวจว่า docs ที่ไม่ใช่ public มี access control จริง
[ ] ตรวจ branch protection ของ repo docs
[ ] ตรวจว่าใครมี write access
[ ] ตรวจ CI token และ deploy token scope
[ ] ตรวจ OpenAPI servers.url ว่าอยู่ใน allowlist
[ ] scan endpoint ภายใน เช่น /admin, /internal, /debug
[ ] ตรวจว่า deployed docs ตรงกับ reviewed source หรือไม่
[ ] ตั้ง versioning สำหรับ API version ที่ยังมีผู้ใช้
[ ] สร้าง audit trail สำหรับการ publish docs

ถ้าพบช่องว่าง ให้จัดลำดับความสำคัญแบบนี้:

1. ปิด docs ที่ควร private แต่ public อยู่
2. จำกัด write access และ deploy token
3. เพิ่ม CI validation สำหรับ OpenAPI
4. แยก internal endpoint ออกจาก public docs
5. ตั้ง versioning และ publish workflow ที่ตรวจสอบได้

สรุป

การละเมิดข้อมูลของ GitHub ไม่ใช่เหตุผลให้เลิกใช้ docs-as-code หรือไม่ไว้ใจ GitHub แต่เป็นเหตุผลให้ตรวจสอบพื้นผิวที่หลายทีมมองข้าม: เอกสาร API ของคุณอยู่ที่ไหน ใครแก้ได้ และผู้ใช้กำลังเชื่อถือข้อมูลชุดใดอยู่

ขั้นตอนถัดไปคือทำ inventory ของเอกสาร API ทั้งหมด ตรวจแต่ละจุดด้วย 4 คุณสมบัติหลัก: access control, versioning, integrity และ audit log ถ้าช่องว่างใหญ่ที่สุดคือ access control ให้ลอง publish เอกสารของโปรเจกต์หนึ่งใน Apidog แล้วตั้ง password หรือ email allowlist เพื่อดูว่า managed documentation layer ช่วยลดความเสี่ยงนี้ได้อย่างไร.