DEV Community

Cover image for วิธี Mock API จาก CLI
Thanawat Wongchai
Thanawat Wongchai

Posted on • Originally published at apidog.com

วิธี Mock API จาก CLI

คุณต้องการ API ปลอมเพื่อพัฒนาในขณะที่แบ็กเอนด์ยังไม่พร้อม บริการภายนอกถูกจำกัดอัตราการเรียกใช้ หรือการทดสอบต้องทำงานโดยไม่เชื่อมต่อเซิร์ฟเวอร์จริง วิธีแก้คือสร้าง mock API แต่คำถามสำคัญคือจะตั้งค่าให้ทำซ้ำได้อย่างไรจาก CLI

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

การคลิกผ่าน GUI เพื่อกำหนด route และ canned response ใช้งานได้สำหรับงานครั้งเดียว แต่ mock ที่สร้างด้วยแอปเดสก์ท็อปมักทำซ้ำ ย้ายเวอร์ชัน หรือสร้างใหม่ใน CI ได้ยาก ในทางกลับกัน mock ที่กำหนดผ่าน CLI คือคำสั่งในสคริปต์ เป็นขั้นตอนใน pipeline และเป็นสิ่งที่ AI coding agent รันได้เหมือนกับนักพัฒนา

บทความนี้ครอบคลุม 2 แนวทาง:

  1. เครื่องมือโอเพนซอร์สที่รัน mock server จากไฟล์ในเครื่อง
  2. CLI ของ Apidog สำหรับนำเข้าสเปกและจัดการ hosted mock expectations

หากต้องการเปรียบเทียบตัวเลือกเพิ่มเติม ดูรายการ เครื่องมือ mock API ที่ดีที่สุด และคู่มือ เครื่องมือ mocking REST API

แนวทางทั่วไป: รันเซิร์ฟเวอร์ mock จากไฟล์

Mock CLI แบบคลาสสิกคือไบนารีขนาดเล็กที่อ่านไฟล์สเปกหรือไฟล์ข้อมูล แล้วเปิดเป็น HTTP endpoint บนพอร์ตในเครื่องทันที ไม่ต้องสร้างโปรเจกต์ ไม่ต้องล็อกอิน และไม่ต้องมีบัญชี

เครื่องมือที่ใช้บ่อยมี 3 กลุ่ม:

  • Prism: สร้าง mock จาก OpenAPI specification
  • Mockoon CLI: รัน environment file หรือ OpenAPI แบบ headless
  • json-server: สร้าง REST API แบบ stateful จาก JSON

Prism: ให้บริการ mock จาก OpenAPI spec

หากมีไฟล์ OpenAPI อยู่แล้ว Prism จาก Stoplight เป็นตัวเลือกที่เริ่มต้นได้เร็วที่สุด มันอ่าน paths, examples และ schemas จากสเปก แล้วตอบกลับตาม contract

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

คำสั่งนี้จะเปิดเซิร์ฟเวอร์ที่ http://127.0.0.1:4010 และเชื่อมทุก operation ที่ประกาศในสเปก

ทดสอบ endpoint ได้ทันที:

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

Prism จะคืนค่า example ที่กำหนดไว้ใน response หากไม่มี example ก็จะสร้างตัวอย่างที่สอดคล้องกับ schema นอกจากนี้ยังตรวจสอบ request ที่เข้ามาตามสเปก ดังนั้น request ที่ไม่ถูกต้องจะได้รับสถานะ 422 แทนที่จะผ่านไปเงียบ ๆ

ติดตั้งแบบ global หากไม่ต้องการใช้ npx:

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

ข้อควรทราบ: Prism เป็นแบบ stateless ดังนั้น POST จะไม่เก็บข้อมูลไว้ เหมาะสำหรับการตรวจสอบ contract มากกว่าการจำลองฐานข้อมูล

Mockoon CLI: รันไฟล์ข้อมูลแบบ headless

Mockoon CLI รัน mock จากไฟล์ environment ที่ export จากแอป Mockoon หรือจาก OpenAPI JSON/YAML ได้โดยตรง เหมาะเมื่อทีมต้องการออกแบบ route แบบ visual ก่อน แล้วนำ environment เดียวกันไปรันใน CI หรือเซิร์ฟเวอร์โดยไม่มี GUI

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

กำหนดพอร์ตเพิ่มเติมได้ด้วย --port:

npx @mockoon/cli start --data ./env.json --port 4000
Enter fullscreen mode Exit fullscreen mode

หากไฟล์ environment มาจาก Mockoon เวอร์ชันเก่า CLI จะย้ายโครงสร้างข้อมูลในหน่วยความจำโดยไม่แก้ไฟล์ต้นฉบับ

ติดตั้งแบบ global:

npm install -g @mockoon/cli
Enter fullscreen mode Exit fullscreen mode

จากนั้นใช้คำสั่ง:

mockoon-cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Mockoon CLI เหมาะเมื่อ route ต้องมีรายละเอียดและการปรับแต่งด้วยมือมากกว่าสเปกเปล่า ๆ แต่ยังต้องรันได้แบบ headless ดูแนวทางเพิ่มเติมได้ในบทความ เซิร์ฟเวอร์ mock น้ำหนักเบาสำหรับ RESTful API

json-server: สร้าง REST API ปลอมจาก JSON

หากยังไม่มี OpenAPI spec json-server เป็นวิธีที่เร็วมากสำหรับสร้าง REST API จากข้อมูล JSON

สร้างไฟล์ db.json:

{
  "posts": [
    {
      "id": 1,
      "title": "Hello mock API"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

เริ่มเซิร์ฟเวอร์:

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

จากนั้นเรียก endpoint ได้ที่:

curl http://localhost:3000/posts
Enter fullscreen mode Exit fullscreen mode

json-server จะสร้าง endpoint พร้อมการทำงานของ GET, POST, PUT, PATCH และ DELETE โดยอัตโนมัติ เช่น:

curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"New post"}'
Enter fullscreen mode Exit fullscreen mode

ข้อมูลที่ POST จะถูกเพิ่มและเขียนกลับลงไฟล์ จึงมีพฤติกรรมแบบ stateful ต่างจาก Prism นอกจากนี้ยังรองรับ filtering, sorting และ pagination ผ่าน query parameters

ติดตั้งแบบ global:

npm install -g json-server
Enter fullscreen mode Exit fullscreen mode

แนวทางโอเพนซอร์สทั้งหมดนี้ใช้งานง่าย: รันจากไฟล์เดียวและไม่มี dependency อื่น ๆ อย่างไรก็ตาม mock, API design และ test อาจแยกกันอยู่คนละไฟล์หรือคนละกระบวนการ หากต้องการ exact request matching หรือ replay ให้พิจารณา MockServer หรือ WireMock ซึ่งมีความสามารถเชิงลึกกว่า แต่ต้องใช้ Java runtime

แนวทาง Apidog CLI: นำเข้าสเปกและสคริปต์ความคาดหวัง

Apidog ใช้แนวทางต่างจาก Prism หรือ json-server อย่างชัดเจน: apidog CLI ไม่ได้ เปิด mock server ในเครื่องจากไฟล์ และไม่มีคำสั่งลักษณะนี้:

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog จะโฮสต์ mock ให้ ส่วน CLI ใช้สำหรับนำเข้าสเปกและจัดการ custom mock expectations

Apidog ไม่ใช่โอเพนซอร์ส แต่เป็นผลิตภัณฑ์เชิงพาณิชย์ที่มีเวอร์ชันฟรี จุดเด่นของแนวทางนี้คือ mock, API design และ test อยู่ในโปรเจกต์เดียวกันและใช้แหล่งความจริงเดียวกัน

หากต้องการ mock ชั่วคราวจากไฟล์เดียว Prism, Mockoon CLI หรือ json-server อาจเหมาะกว่า แต่หาก mock ต้องสอดคล้องกับ API definition และการทดสอบเมื่อ API เปลี่ยนแปลง ให้ใช้แนวทางนี้

ติดตั้ง CLI และยืนยันตัวตนก่อน โดยดูขั้นตอน token ได้จาก คู่มือการติดตั้ง Apidog CLI

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

นำเข้าสเปกเพื่อสร้าง hosted smart mocks

เริ่มจากนำ API definition เข้าโปรเจกต์ Apidog:

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

เมื่อ import แล้ว Apidog จะสร้าง mock URL สำหรับทุก endpoint ที่อยู่ในสเปก

Smart mock อ่าน type และชื่อ field จาก schema ตัวอย่างเช่น:

  • field email สามารถคืนค่าอีเมลที่ดูสมเหตุสมผล
  • field createdAt สามารถคืนค่า timestamp ที่มีรูปแบบเหมาะสม

นอกจาก OpenAPI แล้ว apidog import ยังรองรับ Swagger 2.0, Postman และ Apidog format ทำให้สามารถเปลี่ยน definition ที่มีอยู่เป็น live mock ได้ด้วยคำสั่งเดียว

สร้าง custom response ด้วย apidog mock

Smart mock ครอบคลุมกรณีทั่วไป แต่บางครั้งต้องการ response ที่เจาะจงตาม request เช่น:

  • user ID หนึ่งคืน 200
  • user ID อื่นคืน 404

ในกรณีนี้ให้เพิ่ม mock expectation ผ่านกลุ่มคำสั่ง apidog mock ซึ่งเป็น CRUD สำหรับ expectations ไม่ใช่คำสั่งเริ่ม mock server

ดูคำสั่งที่ใช้ได้:

apidog mock --help
Enter fullscreen mode Exit fullscreen mode

แสดง expectations ทั้งหมดในโปรเจกต์:

apidog mock list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

กรองตาม endpoint:

apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
Enter fullscreen mode Exit fullscreen mode

ผลลัพธ์เป็น JSON จึงสามารถใช้ร่วมกับ jq เพื่อค้นหา expectation ID ได้ เช่น:

apidog mock list --project <PROJECT_ID> | jq '.'
Enter fullscreen mode Exit fullscreen mode

อ่าน แก้ไข หรือลบ expectation:

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

คำสั่ง create และ update รับ definition ผ่าน --file ดังนั้นควรตรวจสอบรูปแบบไฟล์ก่อนเขียนเสมอ

ตรวจสอบไฟล์ expectation ก่อนสร้างหรืออัปเดต

อย่าเขียน JSON โดยเดารูปแบบเอง CLI มี schema สำหรับคำสั่งเขียนทุกประเภท ให้ดึง schema สร้างไฟล์ตาม schema และ validate ก่อนใช้งานจริง

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

ลำดับการทำงานที่แนะนำคือ:

  1. ดึง schema ด้วย cli-schema get
  2. สร้าง mock.json ให้ตรง schema
  3. ตรวจสอบด้วย cli-schema validate
  4. สร้าง expectation ด้วย apidog mock create

หาก validation คืน exit code ที่ไม่ใช่ศูนย์ pipeline จะหยุดก่อนที่ไฟล์ผิดรูปแบบจะถูกส่งไปยังโปรเจกต์

สำหรับการอัปเดต ให้ใช้ schema key mock-update:

apidog cli-schema get mock-update
apidog cli-schema validate mock-update --file ./mock.json
apidog mock update --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

ทุกคำสั่งคืนค่า JSON พร้อม agentHints.nextSteps เพื่อบอกขั้นตอนถัดไปที่ควรรัน จึงเหมาะทั้งกับ workflow ของนักพัฒนาและ AI coding agent ดูกลุ่มคำสั่งเพิ่มเติมได้ใน คู่มือ Apidog CLI ฉบับสมบูรณ์

เชื่อมต่อ mock เข้ากับ CI

ทั้งสองแนวทางใช้ใน CI ได้ เพราะคำสั่งมี exit code และเอาต์พุตชัดเจน

ตัวอย่าง: เปิด Prism เบื้องหลัง แล้วรัน integration tests

# start Prism in the background, then run tests against it
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

สำหรับ Apidog ไม่มี process ในเครื่องที่ต้องเปิดหรือปิด เพราะ mock ถูกโฮสต์ไว้แล้ว ขั้นตอนใน CI จึงเป็นการ validate และ apply expectation ก่อนให้ test เรียก hosted mock URL โดยตรง

# ensure the expectation is well-formed, then apply it
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

ผลลัพธ์คือทีม, CI และ AI agent สามารถตั้งค่า mock API เดียวกันจากชุดคำสั่งเดียวกัน โดยไม่ต้องคลิกผ่าน UI

ปัญหาที่พบบ่อย

คาดหวังว่า apidog mock จะเริ่มเซิร์ฟเวอร์

คำสั่งนี้ไม่เปิด local server ไม่มี apidog mock start, apidog mock serve หรือ apidog mock ./file.yaml

ใช้ apidog import เพื่อนำเข้าสเปกและรับ hosted mocks จากนั้นใช้ apidog mock เพื่อจัดการ custom expectations หากต้องการ process ในเครื่องที่เปิดจากไฟล์ ให้ใช้ Prism, Mockoon CLI หรือ json-server

ข้ามขั้นตอน schema ก่อนเขียน expectation

apidog mock create และ apidog mock update รับไฟล์ผ่าน --file หากรูปแบบไม่ถูกต้อง คำสั่งอาจล้มเหลวหรือให้ผลลัพธ์ที่ไม่ได้ตั้งใจ

ให้รันสองคำสั่งนี้ก่อนเสมอ:

apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

Prism ดูเหมือนตอบข้อมูลว่างหรือไม่สมจริง

คุณภาพของ Prism mock ขึ้นอยู่กับ OpenAPI spec หาก response ไม่มี example และ schema ไม่ชัดเจน mock ที่สร้างได้ก็จะคลุมเครือ

เพิ่มตัวอย่าง response ลงในสเปก เช่น:

responses:
  "200":
    description: Order found
    content:
      application/json:
        schema:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
        example:
          id: "123"
          status: "paid"
Enter fullscreen mode Exit fullscreen mode

ต้องการ stateful behavior จากเครื่องมือ stateless

Prism และ Apidog contract mock ไม่เก็บข้อมูลจาก request ที่เขียนเข้าไป หากต้องการให้ POST แล้ว GET คืน record ที่เพิ่งสร้าง ให้ใช้ json-server หรือกำหนด Apidog expectation ให้คืน response ตามที่ต้องการ

สรุป

การ mock ผ่าน CLI เปลี่ยนงานที่ต้องคลิกใน UI ให้เป็นคำสั่งที่นำไปสคริปต์ ตรวจสอบ และรันใน CI ได้

เลือกเครื่องมือตามสิ่งที่ต้องการ:

สถานการณ์ เครื่องมือที่เหมาะสม
มี OpenAPI spec และต้องการ contract mock ในเครื่อง Prism
มี Mockoon environment หรือ route ที่ปรับแต่งเอง Mockoon CLI
มีเพียง JSON และต้องการ REST API แบบ stateful json-server
ต้องการ hosted mock ที่เชื่อมกับ API design และ test ในโปรเจกต์เดียว Apidog CLI

แนวทางของ Apidog คือ import สเปกเพื่อสร้าง hosted smart mocks แล้วใช้ apidog mock และ cli-schema เพื่อจัดการ custom response อย่างเป็นระบบ

หากต้องการให้ mock สอดคล้องกับ API design และ test ในโปรเจกต์เดียว ให้ดาวน์โหลด Apidog ติดตั้ง CLI และตั้งค่า mock ได้โดยไม่ต้องใช้เมาส์

Top comments (0)