หากคุณมีไฟล์ OpenAPI แต่บริการจริงเริ่มไม่ตรงกับสเปค Specmatic คือเครื่องมือที่ช่วยบังคับให้สเปคกลายเป็น “สัญญาที่รันได้” โดยนำไฟล์เดียวกันไปใช้ทั้งทดสอบบริการจริงและรันเป็น stub สำหรับทีมผู้บริโภค API บทความนี้สรุปวิธีใช้ Specmatic แบบลงมือทำ ความต่างระหว่าง contract testing กับ example-based testing และควรเลือกใช้เมื่อใด พร้อมเทียบกับแนวทางแพลตฟอร์มอย่าง การทดสอบสัญญา API ของ Apidog โดยมี OpenAPI Specification เป็นแหล่งข้อมูลหลักที่ Specmatic อ่านและนำไปตรวจสอบ
Specmatic คืออะไร
Specmatic เป็นเครื่องมือโอเพนซอร์สสำหรับการพัฒนาแบบ contract-driven หลักการคือให้สเปค API เป็นสัญญากลาง แล้วใช้สัญญานั้นตรวจสอบระบบจริงโดยอัตโนมัติ
จากไฟล์ OpenAPI เดียว Specmatic ทำได้ 2 งานหลัก:
- รันเป็นชุดทดสอบกับบริการจริง เพื่อตรวจว่า endpoint, status code, request/response schema และ field ที่จำเป็นตรงตามสเปคหรือไม่
- รันเป็น stub server เพื่อให้ frontend หรือบริการ downstream พัฒนาต่อได้โดยไม่ต้องรอ backend จริง
จุดสำคัญคือคุณไม่ต้องดูแล “สเปค” และ “ชุดทดสอบ” แยกกัน Specmatic อ่านจากไฟล์เดียวกัน เช่น api.yaml หรือ openapi.json
Specmatic รองรับมากกว่า OpenAPI โดยมีการรองรับ AsyncAPI, GraphQL, gRPC รวมถึงรูปแบบอื่นอย่าง WSDL และ Avro แต่สำหรับทีมส่วนใหญ่ จุดเริ่มต้นที่ง่ายที่สุดคือ OpenAPI YAML/JSON
คุณสามารถรันผ่าน CLI หรือ Docker ได้ จึงเหมาะกับการใส่ใน CI pipeline โดยไม่ต้องผูกกับภาษา framework หรือ runtime เฉพาะของโปรเจกต์
Contract testing ต่างจาก Example-based testing อย่างไร
การทดสอบ API แบบทั่วไปมักเป็น example-based testing คือเขียน request ทีละตัว แล้ว assert response เอง เช่น status code ต้องเป็น 200 หรือ field id ต้องมีค่า วิธีนี้ใช้งานง่าย แต่เมื่อ API โตขึ้น คุณต้องดูแล test case จำนวนมาก และมักมีช่องว่างที่ไม่ได้ทดสอบ
Contract testing ใช้วิธีตรงข้าม: ให้สเปคเป็น assertion หลัก Specmatic อ่าน schema แล้วสร้างการทดสอบจากสัญญานั้น เช่น:
- response ต้องตรงกับ schema ที่ประกาศ
- required fields ต้องมีครบ
- status code ต้องอยู่ในรายการที่สเปคกำหนด
- request ที่ไม่ถูกต้องควรถูกปฏิเสธตามสัญญา
| ประเด็น | การทดสอบตามตัวอย่าง | การทดสอบสัญญาด้วย Specmatic |
|---|---|---|
| แหล่งที่มาของความจริง | test case ที่เขียนเอง | OpenAPI spec |
| สิ่งที่ต้องดูแล | request และ assertion ทีละรายการ | spec ที่ทีมใช้อยู่แล้ว |
| ความครอบคลุม | เฉพาะกรณีที่เขียนไว้ | ทุก operation ที่ประกาศในสเปค |
| การตรวจจับ drift | ต้องสังเกตเอง | ตรวจเจออัตโนมัติเมื่อ test fail |
| ความล้มเหลวที่พบบ่อย | ตัวอย่างใดตัวอย่างหนึ่งพัง | service ไม่ตรงกับ contract |
ควรแยกให้ชัดว่า Specmatic ไม่ใช่ Pact broker แบบ consumer-driven contract testing สไตล์ Pact ใน Pact ผู้บริโภคเผยแพร่ expectation ไปยัง broker แล้ว provider ตรวจสอบกับ expectation เหล่านั้น แต่ Specmatic ใช้แนว contract-driven: สเปคเดียวเป็นข้อตกลงร่วมกัน แล้วนำไปตรวจ provider และสร้าง stub ให้ consumer
หากต้องการดูภาพรวมเครื่องมือในกลุ่มนี้เพิ่มเติม อ่านได้ที่ เครื่องมือทดสอบสัญญาและสร้าง mock API
วิธีใช้งาน Specmatic แบบพื้นฐาน
คุณเริ่มได้จาก 2 วิธี:
- ติดตั้ง CLI ในเครื่อง
- ใช้ Docker image ซึ่งเหมาะกับ CI มากกว่า เพราะลดปัญหา dependency ในเครื่อง build
ตัวอย่างสมมติว่าโปรเจกต์มีไฟล์:
.
├── api.yaml
└── service/
และ service จริงรันอยู่ที่:
http://localhost:8080
รัน Contract Test กับบริการจริง
ใช้คำสั่ง specmatic test เพื่อให้ Specmatic อ่านสเปคแล้วส่ง request ไปยังบริการจริง
# รันด้วย CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080
ถ้าใช้ Docker:
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
สิ่งที่เกิดขึ้นคือ:
- Specmatic อ่าน
api.yaml - สร้าง request จาก operation ที่ประกาศไว้ใน OpenAPI
- ยิง request ไปยัง
--testBaseURL - ตรวจ response เทียบกับ status code และ schema ในสเปค
- ถ้าไม่ตรง สั่งให้ test fail
ตัวอย่าง workflow ที่ควรใช้ในทีม:
# 1. start service
docker compose up -d api
# 2. run contract test
specmatic test api.yaml --testBaseURL=http://localhost:8080
# 3. fail build ถ้า service ไม่ตรงกับ spec
ถ้า test fail ให้ตัดสินใจอย่างใดอย่างหนึ่ง:
- service ผิด → แก้ implementation
- spec ล้าสมัย → แก้ OpenAPI spec แล้วให้ทีม review
อย่าปล่อยให้ทั้งสองฝั่ง drift กัน เพราะนั่นคือปัญหาหลักที่ contract testing พยายามแก้
รัน OpenAPI เป็น Stub Server
อีก use case สำคัญคือใช้ Specmatic เป็น stub server เพื่อให้ทีม frontend หรือทีม consumer พัฒนาได้ก่อน backend พร้อม
specmatic stub api.yaml --port=9000
จากนั้น consumer เรียก API ได้ที่:
http://localhost:9000
Specmatic จะสร้าง response ที่ valid ตาม schema โดยอัตโนมัติ เหมาะสำหรับกรณี:
- frontend ต้องเริ่ม integration ก่อน backend เสร็จ
- service downstream ยังไม่พร้อม
- ต้องการ mock ที่ไม่หลุดจากสเปค
- ต้องการ environment เบาสำหรับ local development
ถ้าต้องการ response ที่ควบคุมได้มากขึ้น คุณสามารถใส่ตัวอย่างไว้ในไดเรกทอรี _examples ข้างไฟล์สเปค แล้ว stub จะใช้ตัวอย่างเหล่านั้นเมื่อ request ตรงเงื่อนไข
แนวคิดนี้ใกล้กับ mock server แต่มีจุดต่างคือ stub ของ Specmatic ผูกกับ contract โดยตรง หากต้องการเข้าใจบริบทเพิ่มเติม อ่าน การทดสอบสัญญาและ mock server
ใช้ Specmatic ใน CI Pipeline
รูปแบบที่ใช้ได้จริงคือให้ CI ทำงานตามลำดับนี้:
name: Contract Test
on:
pull_request:
push:
branches:
- main
jobs:
contract-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Start API service
run: docker compose up -d api
- name: Run Specmatic contract tests
run: |
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
เป้าหมายคือทำให้ pull request ที่เปลี่ยน API แต่ไม่อัปเดตสเปค fail ทันที หรือถ้าเปลี่ยนสเปคแต่ implementation ยังไม่รองรับ ก็ fail เช่นกัน
นี่ทำให้ OpenAPI ไม่ใช่เอกสารที่เขียนไว้เฉยๆ แต่เป็น gate ของ delivery pipeline
โมเดล “Spec เป็น Contract และ Stub”
ประโยชน์หลักของ Specmatic คือให้ไฟล์เดียวทำหน้าที่ทั้งสองฝั่ง:
- ฝั่ง provider ใช้
specmatic testเพื่อพิสูจน์ว่า service ตรงกับ contract - ฝั่ง consumer ใช้
specmatic stubเพื่อพัฒนากับ API ที่ตรงกับ contract เดียวกัน
ดังนั้นทีมไม่ต้องถกกันว่า mock ที่ใช้ใน frontend ตรงกับ backend จริงหรือไม่ เพราะทั้ง test และ stub อ่านจากสเปคเดียวกัน
ถ้าคุณยังสับสนระหว่าง stub และ mock แนะนำให้อ่าน การทำ API stubbing vs mocking ก่อนออกแบบ workflow
ตรวจ Backward Compatibility
Specmatic ยังมีคำสั่งสำหรับตรวจ backward compatibility เช่นกรณีมี OpenAPI เวอร์ชันเก่าและใหม่ แล้วต้องการรู้ว่าเวอร์ชันใหม่ทำให้ consumer เดิมพังหรือไม่
แนวคิดคือ:
- ใช้สเปคเวอร์ชันใหม่เริ่ม stub
- สร้าง test จากสเปคเวอร์ชันเก่า
- รัน test เก่ากับ stub ใหม่
- ถ้า test fail แปลว่า contract ใหม่อาจ breaking change
สิ่งนี้มีประโยชน์มากใน microservices ที่ deploy แยกกัน เพราะช่วยตรวจ breaking change ก่อนปล่อยจริง แนวคิดนี้เกี่ยวข้องกับ การทดสอบสัญญาแบบสองทิศทาง
สร้าง OpenAPI จาก Traffic จริง
หากคุณมี service อยู่แล้วแต่ยังไม่มี OpenAPI spec อย่างเป็นทางการ Specmatic สามารถทำงานเป็น proxy เพื่อจับ request/response จริง แล้วสร้างเอกสาร OpenAPI พร้อมตัวอย่างจาก traffic ที่ตรวจพบได้
เหมาะกับกรณี:
- legacy service ไม่มี spec
- ต้องเริ่มทำ contract testing จากระบบที่มีอยู่
- ต้องการสร้าง baseline spec จากพฤติกรรมจริงก่อนค่อยปรับให้เป็นทางการ
หลังจากได้ spec แล้ว ควรให้ทีม review และทำให้ schema ชัดเจนขึ้นก่อนนำไปใช้เป็น contract ใน CI
Specmatic เหมาะกับทีมแบบไหน
Specmatic เหมาะเมื่อทีมของคุณมีเงื่อนไขเหล่านี้:
- มี OpenAPI, AsyncAPI, GraphQL หรือ gRPC spec ที่เชื่อถือได้
- มี provider และ consumer หลายทีมที่ต้องทำงานร่วมกัน
- ต้องการให้ build fail เมื่อ API ไม่ตรงกับสเปค
- ใช้ CLI และ CI เป็น workflow หลัก
- ต้องการ stub ที่ผูกกับ contract จริง ไม่ใช่ mock ที่เขียนแยก
อาจไม่เหมาะหากคุณ:
- ยังไม่มีสเปคและไม่พร้อมดูแลสเปค
- ต้องการ visual workspace สำหรับออกแบบ API
- ต้องการเครื่องมือเดียวสำหรับ debug, document, mock, test และ collaborate
- ต้องการ Pact broker แบบ consumer-driven โดยเฉพาะ
Specmatic เทียบกับ Apidog
Specmatic เป็นเครื่องมือ contract engine ที่ชัดเจนและเน้น CLI ส่วน Apidog เป็นแพลตฟอร์ม schema-driven ที่รวมงาน API หลายส่วนไว้ใน workspace เดียว เช่น design, testing, mock และ documentation
Apidog อ่าน OpenAPI schema, ตรวจ response เทียบกับ schema และสร้าง mock server จาก OpenAPI schema ของคุณ ได้โดยไม่ต้องเขียนโค้ด
ความต่างหลักคือขอบเขต:
- Specmatic: เหมาะกับ contract testing/stubbing แบบ CLI-native
- Apidog: เหมาะกับทีมที่ต้องการพื้นที่ทำงานแบบภาพสำหรับออกแบบ ทดสอบ mock และทำเอกสารในที่เดียว
ทั้งสองไม่ใช่ Pact broker แบบ consumer-driven ดังนั้นถ้าทีมต้องการ broker สำหรับ pact โดยเฉพาะ ควรเลือกเครื่องมือในกลุ่ม Pact โดยตรง
หากต้องการสร้างชุดทดสอบจากสเปคใน workspace เดียว ดูตัวอย่างได้ที่ การสร้างชุดทดสอบ API จากสเปค OpenAPI
คำถามที่พบบ่อย
Specmatic ใช้งานได้ฟรีหรือไม่?
ใช่ เอนจิน contract หลักเป็นโอเพนซอร์สและใช้งานได้ฟรีผ่าน CLI หรือ Docker คุณสามารถรัน contract test และ stub server จาก OpenAPI spec ได้โดยไม่ต้องเสียค่าใช้จ่าย ส่วนข้อเสนอเชิงพาณิชย์ให้ตรวจสอบจากเว็บไซต์ทางการและ GitHub สำหรับรายละเอียดล่าสุด
Specmatic ใช้ได้เฉพาะ OpenAPI หรือไม่?
ไม่ใช่ OpenAPI เป็นจุดเริ่มต้นที่พบบ่อยที่สุด แต่ Specmatic ยังรองรับ AsyncAPI สำหรับ event-driven contract รวมถึง GraphQL และ gRPC ตั้งแต่เวอร์ชัน 2.0 พร้อมรูปแบบอื่นอย่าง WSDL และ Avro หลักการเหมือนกันคือให้สเปคเป็น contract ที่รันได้ หากยังใหม่กับ OpenAPI อ่านพื้นฐานได้ที่ บทแนะนำ OpenAPI Specification
Specmatic เหมือน Pact หรือไม่?
ไม่เหมือนโดยตรง Pact เป็น consumer-driven contract testing ผู้บริโภคเผยแพร่ expectation ไปยัง broker แล้ว provider ตรวจสอบกับ expectation เหล่านั้น ส่วน Specmatic เป็น contract-driven โดยใช้สเปคเดียวเป็นสัญญากลาง แล้วนำไปตรวจ provider และสร้าง stub ให้ consumer
Specmatic สร้าง OpenAPI spec ให้ได้หรือไม่?
ได้ Specmatic สามารถทำงานเป็น proxy หน้าบริการที่มีอยู่ จับ traffic จริง และสร้าง OpenAPI document พร้อมไฟล์ตัวอย่างจาก request/response ที่พบ เหมาะสำหรับเริ่มทำ contract testing กับ service ที่มีอยู่แล้วแต่ยังไม่มีสเปคทางการ
สรุป
Specmatic เหมาะสำหรับทีมที่ต้องการทำให้ OpenAPI spec เป็น contract ที่ตรวจสอบได้จริง คุณสามารถใช้ไฟล์เดียวกันรัน contract test กับบริการจริง รัน stub ให้ consumer และตรวจ backward compatibility ใน CI ได้
ถ้าทีมของคุณเน้น terminal และ pipeline เป็นหลัก Specmatic เป็นเครื่องมือที่ตรงจุดมาก แต่ถ้าคุณต้องการ workspace แบบภาพที่รวม contract, test, mock และ documentation ไว้ด้วยกัน ลองใช้ Apidog ซึ่งช่วยตรวจ response เทียบกับ schema สร้าง mock endpoint โดยไม่ต้องเขียนโค้ด และเปลี่ยนสเปคเป็นชุดทดสอบที่รันได้ คุณสามารถ ดาวน์โหลด Apidog แล้วนำ OpenAPI spec ของคุณเข้าไปเริ่ม workflow ตั้งแต่ออกแบบจนถึงทดสอบได้ในที่เดียว
Top comments (0)