Thanawat Wongchai

Posted on Jun 2 • Originally published at apidog.com

วิธีสร้างและโฮสต์ API Docs จาก Bruno

ถ้าคุณใช้ Bruno อยู่แล้ว จุดแข็งของมันชัดเจนมาก: คอลเลกชัน API ถูกเก็บเป็นไฟล์ .bru ใน Git repo เดียวกับโค้ด ทำงานแบบ offline-first และไม่บังคับให้ฝากข้อมูลไว้บนคลาวด์ เหมาะกับทีมที่ต้องการ version control สำหรับ request, environment และ notes ของ API แบบตรงไปตรงมา

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

แต่เมื่อทีมเริ่มต้องแชร์ API ให้ frontend, QA, partner หรือ developer ภายนอก คำถามจะเปลี่ยนจาก “ยิง request ได้ไหม” เป็น “เอกสารอยู่ที่ไหน ส่งลิงก์ให้ได้ไหม” ตรงนี้ Bruno ยังไม่ใช่เครื่องมือสำหรับเผยแพร่ API documentation แบบ hosted portal โดยตรง บทความนี้สรุปแนวทางที่ใช้งานได้จริง: Bruno ให้คุณได้อะไร, ขาดอะไร และถ้าต้องการ URL เอกสาร API ที่แชร์ได้ ควรจัดการอย่างไรจาก OpenAPI spec

สิ่งที่ทีมต้องการจริงๆ จากเอกสาร API

ก่อนเลือกเครื่องมือ ให้กำหนดก่อนว่า “API documentation” ต้องแก้ปัญหาอะไรบ้าง สำหรับทีมพัฒนาโดยทั่วไป เอกสารที่ใช้งานได้จริงควรมี 3 อย่างนี้:

URL ที่แชร์ได้

คนอื่นต้องอ่านเอกสารได้โดยไม่ต้อง clone repo, ติดตั้ง client หรือเปิดไฟล์ .bru เอง แค่ส่งลิงก์ใน Slack, Jira หรือ email แล้วเปิดอ่านได้ทันที
เอกสารที่ซิงค์กับ API จริง

ถ้า endpoint เปลี่ยน แต่เอกสารไม่เปลี่ยน เอกสารจะกลายเป็นแหล่งข้อมูลที่ทำให้เข้าใจผิด ดังนั้น source of truth ควรเป็น spec ที่ตรวจสอบได้ เช่น OpenAPI
โหมด “ลองใช้” แบบ interactive

Developer ไม่ได้ต้องการอ่าน description อย่างเดียว แต่ต้องการส่ง request จริง ดู response จริง และเข้าใจ auth, headers, query params และ payload จากตัวอย่างที่พร้อมใช้งาน

ถ้าเอกสารทำได้ครบ 3 ข้อนี้ มันจะกลายเป็น reference ที่ทีมใช้งานได้จริง ไม่ใช่ไฟล์ README ที่ต้องคอยอัปเดตด้วยมือ

Bruno ช่วยเรื่องเอกสารได้แค่ไหน

Bruno มีจุดแข็งสำหรับการทำงานใน repo:

ไฟล์ .bru เป็น plain text อ่านได้
request, headers, body และ metadata อยู่ใน Git
review ผ่าน pull request ได้
รองรับ docs block สำหรับอธิบาย request
มี Markdown documentation view ภายในแอป

ตัวอย่างแนวคิดของไฟล์ request ใน Bruno:

meta {
  name: Get User
  type: http
}

get {
  url: {{baseUrl}}/users/:id
}

params:path {
  id: 123
}

headers {
  Authorization: Bearer {{token}}
}

docs {
  ดึงข้อมูลผู้ใช้จาก user id
}

สำหรับทีม internal ที่ทุกคนใช้ Bruno และเข้าถึง repo ได้ วิธีนี้ถือว่าเพียงพอในระดับหนึ่ง เพราะเอกสารอยู่ใกล้กับ request และถูก version control ไปพร้อมกับโค้ด

แต่ข้อจำกัดสำคัญคือ การเผยแพร่เอกสาร:

Bruno ไม่มี hosted public documentation portal ในตัว
ไม่มีปุ่ม publish ที่เปลี่ยน collection เป็นเว็บเอกสาร
คนอ่านต้องติดตั้ง Bruno และ clone collection ก่อน
ไม่มี URL เอกสารที่เสถียรสำหรับส่งให้คนภายนอก
ถ้าต้องการเว็บเอกสาร ต้องพึ่ง pipeline หรือเครื่องมือแยก

ดังนั้น Bruno เหมาะกับการจัดการ request และ notes ใน Git แต่ถ้าต้องการ documentation portal ที่แชร์ได้ ต้องมีขั้นตอนเพิ่ม

หลักการ Docs-as-Code

แนวทางที่ยั่งยืนกว่าคือทำให้เอกสารเป็นผลลัพธ์จาก API spec ไม่ใช่ไฟล์ที่เขียนแยก

ใน เวิร์กโฟลว์ docs-as-code API จะถูกอธิบายด้วย spec ที่เครื่องอ่านได้ เช่น OpenAPI แล้วใช้ spec เดียวกันนี้สร้างสิ่งอื่นต่อ:

API documentation
mock server
test cases
client SDK
contract review
schema validation

ตัวอย่าง OpenAPI แบบย่อ:

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: Get user by id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
        email:
          type: string
          format: email

เมื่อ spec อยู่ใน Git และถูก review ผ่าน pull request ทีมจะได้ source of truth เดียว เอกสารจึงไม่ต้องอัปเดตแยกด้วยมือ เพราะมันถูกสร้างจาก spec โดยตรง

สร้างและโฮสต์เอกสารจาก OpenAPI spec

ช่องว่างที่ Bruno ยังไม่ได้แก้คือการ publish documentation portal ที่ใช้งานได้ทันที ตรงนี้ Apidog เข้ามาช่วยใน workflow แบบ spec-first: นำเข้า OpenAPI แล้วสร้างเอกสารแบบ hosted และ interactive จาก spec เดียวกัน

ผลลัพธ์ที่ได้คือ documentation portal ที่:

มี URL สำหรับแชร์ให้ developer คนอื่น
อ่านได้โดยไม่ต้องติดตั้ง Bruno หรือ clone repo
รองรับการตั้งค่า visibility เช่น public, private หรือ password-protected
แนบ custom domain ได้ เช่น docs.yourcompany.com
มีแผง “ลองใช้” สำหรับยิง request จากหน้าเอกสาร
สร้างจาก spec จึงลดโอกาสเอกสารคลาดเคลื่อนจาก API จริง

แนวคิดคือไม่ต้องดูแลเอกสาร 2 ชุด คุณดูแล OpenAPI spec ชุดเดียว แล้วให้เครื่องมือสร้างเอกสารจาก spec นั้น

Workflow แนะนำ: จาก Bruno ไปสู่ URL เอกสารที่แชร์ได้

ถ้าคุณมี Bruno collection อยู่แล้ว ให้ใช้ workflow นี้:

ตรวจ request ใน Bruno ให้ครบ
- ตรวจ method
- ตรวจ URL
- ตรวจ headers
- ตรวจ auth
- ตรวจ request body
- ตรวจตัวอย่าง response ถ้ามี
แปลง collection หรือ request definition เป็น OpenAPI
- เป้าหมายคือให้ได้ไฟล์ openapi.yaml หรือ openapi.json
- เก็บไฟล์นี้ไว้ใน repo
- review ผ่าน pull request
ตรวจ OpenAPI spec
- ตรวจ paths
- ตรวจ schemas
- ตรวจ required fields
- ตรวจ response status codes
- ตรวจ security schemes
นำเข้า spec เข้า Apidog
- import OpenAPI spec
- ตรวจ endpoint, schema และ example ที่ถูกสร้าง
- ปรับ description หรือ example เพิ่มถ้าจำเป็น
ตั้งค่า documentation
- เลือก visibility
- ตั้งชื่อเอกสาร
- ตั้งค่า environment หรือ base URL
- ตั้งค่า custom domain ถ้าต้องการ
publish
- ได้ URL เอกสารที่แชร์ได้
- ส่งให้ frontend, QA, partner หรือ external developer ใช้งาน

สรุปเป็นตาราง:

ขั้นตอน	การกระทำ	ผลลัพธ์
1	เตรียม request ใน Bruno ให้ครบ	มีข้อมูล endpoint, auth, headers และ body พร้อมแปลงเป็น spec
2	แปลงหรือเขียน OpenAPI spec	ได้ไฟล์ `openapi.yaml` หรือ `openapi.json`
3	เก็บ spec ใน Git และ review ผ่าน pull request	spec กลายเป็น source of truth ของ API
4	นำเข้า OpenAPI ใน Apidog	endpoints, schemas และ examples ถูกสร้างจาก spec
5	ตั้งค่า visibility และ custom domain ถ้าต้องการ	เอกสารพร้อมเผยแพร่ตามรูปแบบที่ทีมต้องการ
6	Publish	ได้ hosted documentation URL ที่แชร์ได้

ทำให้เอกสารซิงค์กับ API เมื่อ spec เปลี่ยน

URL เอกสารจะมีประโยชน์ก็ต่อเมื่อเนื้อหายังถูกต้อง ดังนั้น workflow ควรบังคับให้การเปลี่ยน API ต้องเปลี่ยน spec ด้วย

ตัวอย่างแนวทางที่ใช้ได้จริง:

ถ้าเปลี่ยน endpoint:
- แก้ implementation
- แก้ OpenAPI spec
- แก้หรือเพิ่ม test
- review ทั้งหมดใน pull request เดียวกัน
- publish documentation จาก spec ล่าสุด

ตัวอย่าง checklist ใน pull request:

## API change checklist

- [ ] อัปเดต OpenAPI paths แล้ว
- [ ] อัปเดต request schema แล้ว
- [ ] อัปเดต response schema แล้ว
- [ ] เพิ่มตัวอย่าง request/response แล้ว
- [ ] ตรวจ breaking change แล้ว
- [ ] เอกสารที่ publish แล้วสะท้อน spec ล่าสุด

เมื่อทุกอย่างผูกกับ spec เดียว เอกสารจะไม่ใช่งานแยกที่ต้องอาศัยความจำของทีม แต่เป็นผลลัพธ์ปกติของการเปลี่ยน API

เมื่อไหร่ควรใช้ Bruno ต่อ และเมื่อไหร่ควรเพิ่ม hosted docs

Bruno ยังเหมาะกับงานเหล่านี้:

ทดสอบ request ภายในทีม
เก็บ collection ใน Git
ทำงาน offline-first
review request definition ผ่าน pull request
ใช้เป็น API client สำหรับ developer

แต่ถ้าทีมเริ่มมี requirement เหล่านี้ ควรเพิ่ม hosted documentation workflow:

ต้องส่งลิงก์เอกสารให้คนที่ไม่ได้ใช้ Bruno
ต้องเปิดเอกสารให้ partner หรือ external developer
ต้องมี interactive API docs
ต้องใช้ custom domain
ต้องลดปัญหาเอกสารไม่ตรงกับ API
ต้องการให้ OpenAPI เป็น source of truth

แนวทางที่ practical คือไม่จำเป็นต้องทิ้ง Bruno ทันที แต่ให้ย้าย documentation source ไปอยู่ที่ OpenAPI spec แล้วใช้เครื่องมือสำหรับ publish เอกสารจาก spec นั้น

คำถามที่พบบ่อย

Bruno สามารถสร้างและโฮสต์เอกสาร API สาธารณะได้หรือไม่?

Bruno มีไฟล์ .bru ที่อ่านได้และมี Markdown documentation view ภายในแอป แต่ไม่ได้มี hosted public documentation portal พร้อม URL ที่แชร์ได้ในตัว ถ้าต้องการเอกสารสาธารณะ ทีมมักต้อง export หรือแปลงเป็น OpenAPI แล้วใช้เครื่องมือสร้างเอกสารแยกต่างหาก

ฉันจะได้ URL เอกสาร API ที่แชร์ได้อย่างไร?

ให้เริ่มจาก OpenAPI spec จากนั้นใช้เครื่องมือที่สร้าง hosted documentation จาก spec นั้น ใน Apidog คุณสามารถนำเข้า spec, ตั้งค่า visibility, เลือก custom domain ได้ และ publish ออกมาเป็น URL เอกสารที่ใช้งานได้จริง พร้อมโหมด “ลองใช้”

ฉันต้องเลิกใช้ Bruno เพื่อเผยแพร่เอกสารหรือไม่?

ไม่จำเป็น คุณยังใช้ Bruno สำหรับการยิง request และทำงานภายใน repo ได้ แต่ให้แปลงหรือดูแล API contract เป็น OpenAPI spec จากนั้นใช้ spec นั้นในการสร้างเอกสารที่โฮสต์และแชร์ได้

ทำไมไม่เขียน README เอง?

README ใช้ได้สำหรับข้อมูลสั้นๆ แต่ไม่เหมาะเป็น API documentation หลักเมื่อ API โตขึ้น เพราะต้องอัปเดตด้วยมือและมักคลาดเคลื่อนจาก implementation จริง ถ้าใช้ OpenAPI spec เป็น source of truth เอกสารจะถูก generate จาก contract โดยตรง ลดงานซ้ำและลดความผิดพลาด

ถ้า endpoint เปลี่ยน เอกสารจะอัปเดตอย่างไร?

ให้เปลี่ยน OpenAPI spec พร้อมกับ code change ใน pull request เดียวกัน เมื่อ spec ใหม่ถูกนำไป publish เอกสารก็จะแสดง endpoint, schema และตัวอย่างตามสถานะล่าสุดของ API โดยไม่ต้องเขียนเอกสารแยกอีกชุดหนึ่ง

DEV Community