คุณมี endpoint ที่กำหนดไว้แล้วและต้องการเรียกใช้จากแอปของคุณ ส่วนที่น่าเบื่อคือการแปลข้อกำหนดให้เป็นโค้ดที่ใช้งานได้จริง: URL ที่ถูกต้อง, ส่วนหัว, โทเค็นการตรวจสอบสิทธิ์, สตริงแบบสอบถาม ทั้งหมดนี้เชื่อมต่อกับการเรียกใช้ requests หรือ fetch หากคุณคัดลอกตัวอักษรผิดไปหนึ่งตัว คุณอาจใช้เวลาถึงยี่สิบนาทีสงสัยว่าทำไมเซิร์ฟเวอร์ถึงคืนค่า 401
คุณไม่จำเป็นต้องเขียน boilerplate ด้วยมือ หาก API ของคุณได้รับการออกแบบใน Apidog แพลตฟอร์มจะอ่านข้อกำหนด endpoint ของคุณและส่งมอบ request snippet ที่พร้อมวางในภาษาที่คุณใช้ทำงาน: cURL สำหรับการตรวจสอบอย่างรวดเร็วในเทอร์มินัล, Python requests สำหรับสคริปต์, JavaScript fetch หรือ Axios สำหรับส่วนหน้า คู่มือนี้จะนำเสนอการสร้างโค้ดนั้นจาก endpoint จริง, เวลาที่ควรส่งคำขอก่อนเพื่อให้ snippet มีค่าจริง, และวิธีรักษาโค้ดที่สร้างขึ้นให้ถูกต้องเมื่อข้อกำหนดของคุณเปลี่ยนแปลงไป หากคุณต้องการภาพรวมของตัวเลือกที่กว้างขึ้น บทความสรุปของเราเกี่ยวกับ เครื่องมือสร้างโค้ด API จะให้มุมมองที่กว้างขึ้น; ที่นี่เราจะเน้นการใช้งานจริงกับตัวสร้างโค้ดในตัว
แนวคิดนี้อยู่บนพื้นฐานที่ว่าข้อกำหนดเป็นแหล่งความจริงแหล่งเดียว ซึ่งเป็นหลักการเดียวกับ OpenAPI Specification กำหนดคำจำกัดความให้ถูกต้องเพียงครั้งเดียว แล้วโค้ดคำขอจะตามมาเอง
ตัวสร้างโค้ดไคลเอ็นต์ทำอะไรบ้าง
Apidog แปลคำจำกัดความ endpoint ให้เป็น request snippet สำหรับภาษาต่างๆ เลือก GET /orders, เลือก Python และไลบรารี Requests แล้วมันจะเขียนการเรียกใช้ที่ส่งไปยังพาธนั้นพร้อมกับส่วนหัวและพารามิเตอร์ที่ข้อกำหนดของคุณประกาศไว้ มันคือตัวสร้างคำขอ: มันสร้างโค้ดสำหรับการเรียกใช้หนึ่งครั้ง ในไวยากรณ์ของภาษาและไลบรารี HTTP ที่คุณเลือก
กำหนดความคาดหวังให้ถูกต้องในประเด็นหนึ่ง ฟีเจอร์นี้สร้างโค้ดคำขอหรือไคลเอ็นต์สำหรับ endpoint ไม่ใช่ SDK เต็มรูปแบบ หรือแพ็คเกจไลบรารีไคลเอ็นต์ที่มีเวอร์ชัน หากคุณต้องการบรรทัด cURL, บล็อก Python requests หรือ snippet JS fetch เพื่อนำไปใส่ในโค้ดของคุณ นั่นคือสิ่งที่คุณจะได้รับ เอกสารไม่ได้อธิบายถึงตัวสร้างไลบรารีเต็มรูปแบบ ดังนั้นอย่าคาดหวัง SDK แบบพิมพ์ที่ดาวน์โหลดได้พร้อมโมเดลและตัวช่วยการแบ่งหน้า
สิ่งนี้เข้ากันได้ดีกับเวิร์กโฟลว์ การพัฒนา API แบบ Design-first คุณกำหนดสัญญา สร้างโค้ดคำขอจากสัญญาโดยตรง และผู้ใช้ทุกคนจะเริ่มต้นจากคำจำกัดความที่ถูกต้องเดียวกัน แทนที่จะเป็นภาพหน้าจอที่วางลงใน Slack
สองวิธีในการเปิดตัวสร้างโค้ด
Apidog ให้คุณมีจุดเข้าถึงสองจุดสำหรับคุณสมบัติเดียวกัน ใช้จุดที่ตรงกับตำแหน่งที่คุณอยู่แล้ว
วิธีแรกคือจากเอกสาร เปิดแท็บ Documentation สำหรับ API ของคุณ จากนั้นคลิกปุ่ม Generate Client Code ที่ด้านขวา นี่คือเส้นทางที่เร็วที่สุดเมื่อคุณกำลังอ่านเอกสารของ endpoint และต้องการเรียกใช้
วิธีที่สองคือจากตัวรัน ในแท็บ Run ของ API ให้คลิกไอคอนโค้ด </> ซึ่งอยู่ข้างๆ ที่คุณสร้างและส่งคำขอ ดังนั้นจึงเป็นทางเลือกที่เหมาะสมเมื่อคุณกำลังทดสอบการเรียกใช้อยู่แล้ว
ทั้งสองวิธีจะเปิดแผงเดียวกัน จากนั้นคุณเลือกภาษาและรูปแบบ และ Apidog จะเขียน snippet ให้
สร้างการเรียกใช้ไคลเอ็นต์ Python สำหรับ GET /orders
นี่คือขั้นตอนทั้งหมดพร้อมกับ endpoint ที่สมจริง: การเรียกใช้ GET /orders ที่แสดงรายการคำสั่งซื้อของลูกค้า โดยกรองตามสถานะและมีการแบ่งหน้า
ขั้นตอนที่ 1: เปิด endpoint และเลือกภาษาของคุณ
เปิดแท็บ Documentation สำหรับ endpoint และคลิก Generate Client Code ในแผง ให้เลือกเป้าหมายของคุณ Apidog รองรับภาษาและรูปแบบต่างๆ มากมาย เพื่อให้คุณสามารถจับคู่กับ stack ของคุณได้อย่างแม่นยำ:
- Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
- JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
- Python: http.client, Requests
- Java: Unirest, OkHttp
- Go: Native
- PHP: cURL, Guzzle, pecl_http, HTTP_Request2
- Others: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, พร้อมตัวเลือก HTTP แบบดิบ
สำหรับตัวอย่างนี้ เลือก Python และรูปแบบ Requests Apidog จะสร้างบางอย่างเช่นนี้จากข้อกำหนด:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {"Accept": "application/json"}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
คัดลอก, วางลงในสคริปต์ของคุณ, แล้วมันก็จะใช้งานได้ นั่นคือเส้นทางแบบ design-first: snippet สะท้อนสิ่งที่ endpoint ของคุณประกาศไว้อย่างแม่นยำ
ขั้นตอนที่ 2: ทำความเข้าใจว่า snippet ที่มาจากข้อกำหนดเท่านั้นมีอะไรบ้าง
มีข้อควรระวังที่ควรทำความเข้าใจก่อนที่คุณจะวางโค้ด โค้ดที่สร้างขึ้นโดยตรงจากข้อกำหนด API จะรวมเฉพาะข้อกำหนด API เท่านั้น ไม่ใช่ค่าพารามิเตอร์คำขอจริงหรือโทเค็นการอนุญาตของคุณ คุณจะได้รับโครงสร้างของการเรียกใช้และค่าตัวอย่างใดๆ ที่กำหนดไว้ในข้อกำหนด แต่ไม่ใช่ส่วนหัว Authorization: Bearer ... ที่ใช้งานจริงที่คุณต้องใช้เพื่อเข้าถึง endpoint ที่มีการป้องกัน
นั่นใช้ได้กับการเรียกใช้ที่ไม่มีการยืนยันตัวตน หรือเมื่อคุณจะกรอกโทเค็นด้วยตัวเอง สำหรับ GET /orders ที่มีการป้องกัน คุณต้องการค่าจริงในโค้ด
ขั้นตอนที่ 3: ส่งคำขอก่อนเพื่อเก็บค่าจริง
เพื่อให้ได้ snippet ที่มีค่าพารามิเตอร์จริงและข้อมูลการอนุญาต ให้ส่งคำขอก่อน จากนั้นอ่านโค้ดจากแท็บ Actual Request
หากคุณทำงานแบบ design-first นี่เป็นเรื่องง่าย กำหนด endpoint ในแท็บ Edit คลิกแท็บ Run และพารามิเตอร์คำขอจะถูกเติมอัตโนมัติจากข้อกำหนด หากคุณต้องการตั้งค่าด้วยตัวเอง (โหมด request-first) ให้ป้อนพารามิเตอร์คำขอด้วยตนเองในแท็บ Run แทน ไม่ว่าด้วยวิธีใด ให้เพิ่มโทเค็นการอนุญาตของคุณ จากนั้นคลิก Send เพื่อส่งคำขอ
เมื่อได้รับคำตอบแล้ว ให้สลับไปที่แท็บ Actual Request แล้วเลื่อนลงเพื่อค้นหาโค้ดไคลเอ็นต์ ตอนนี้ snippet ที่สร้างขึ้นจะรวมค่าที่เป็นรูปธรรมและส่วนหัวการอนุญาตที่ถูกส่งไปจริง:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {
"Accept": "application/json",
"Authorization": "Bearer sk_live_51H8xY2..."
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
นั่นคือความแตกต่างระหว่างสองเส้นทาง โหมด Design-first จะเติมพารามิเตอร์อัตโนมัติจากข้อกำหนด; โหมด Request-first ช่วยให้คุณพิมพ์ค่าเหล่านั้นได้ ทั้งสองโหมดจะส่ง snippet Actual Request เดียวกันเมื่อคุณกด Send ปฏิบัติต่อโทเค็นจริงเช่นตัวอย่างข้างต้นว่าเป็นความลับและเก็บไว้ไม่ให้เข้าสู่สิ่งที่คุณจะคอมมิตไปยัง git; การดูแลรักษาเช่นเดียวกับที่ เอกสารของ Stripe แนะนำสำหรับคีย์ที่ใช้งานจริงก็ใช้ได้ที่นี่
การจัดการเนื้อหาคำขอสำหรับ POST และ PUT
GET /orders ไม่มีเนื้อหา แต่เมื่อคุณสร้างโค้ดสำหรับ POST /orders หรือ PUT /orders/{id} คุณจะต้องมีเนื้อหาคำขอใน snippet Apidog ช่วยคุณสร้างในแท็บ Run ก่อนที่คุณจะสร้างโค้ด
สำหรับเนื้อหา JSON หรือ XML คุณมีสองแหล่งที่มา ใช้ตัวอย่างที่กำหนดไว้ล่วงหน้าจากข้อกำหนด endpoint หรือคลิก Auto-generate เพื่อสร้างโครงสร้างเนื้อหาที่ตรงกับ schema ของคุณ เมนูดรอปดาวน์ Auto-generate มีสองโหมด:
- Examples: เลือกตัวอย่างเนื้อหาคำขอที่กำหนดไว้ล่วงหน้าด้วยตนเอง
- Generate Each Time: สร้างข้อมูลใหม่ทุกครั้งที่ใช้งาน โดยปฏิบัติตามกฎการจำลองอัจฉริยะเพื่อให้คุณได้รับค่าใหม่ที่ถูกต้องตาม schema ทุกครั้ง
คุณสามารถควบคุมวิธีการสร้างข้อมูลผ่านตัวเลือกย่อย Auto-generation Preference: Use Example Values First, Use Default Values First, Use Mock Value, Generate Field Names Only และ Use Request Example เลือก Use Example Values First เมื่อข้อกำหนดของคุณมีตัวอย่างที่ดีและคุณต้องการให้เป็นไปตามนั้น; เลือก Use Mock Value เมื่อคุณต้องการข้อมูลที่สร้างขึ้นอย่างสมจริงสำหรับทุกฟิลด์
ข้อควรทราบเกี่ยวกับเวอร์ชัน: ตัวเลือก Auto-generate สำหรับเนื้อหาคำขอต้องใช้ Apidog 2.7.0 หรือใหม่กว่า หากคุณไม่เห็นตัวเลือกเหล่านี้ ให้อัปเดตแอป Schema ที่ระบุไว้อย่างดีพร้อมตัวอย่าง ซึ่งเป็นประเภทที่คุณได้รับจาก การสร้างเอกสาร API อัตโนมัติจาก OpenAPI ทำให้ขั้นตอนนี้สร้างเนื้อหาที่สะอาดโดยแทบไม่ต้องแก้ไขด้วยตนเอง
เมื่อคุณต้องการค่าที่เปลี่ยนแปลงไปตามคำขอ เช่น การประทับเวลาใหม่ หรือ ID คำสั่งซื้อแบบสุ่ม ให้แทรกค่าไดนามิกแทนที่จะฮาร์ดโค้ดค่าใดค่าหนึ่ง คลิกไอคอน ไม้กายสิทธิ์ ที่อยู่ถัดจากช่องป้อนพารามิเตอร์ หรือใช้ปุ่ม Insert Dynamic Value ภายในเนื้อหาคำขอ JSON หรือ XML หลังจากเนื้อหาพร้อมแล้ว คลิก Send จากนั้นอ่าน snippet ที่เสร็จสมบูรณ์จากแท็บ Actual Request ดังเดิม
เมื่อไหร่ที่ควรใช้ request snippet เทียบกับการเรียกใช้ business-model
การตัดสินใจอย่างรวดเร็ว: คุณควรคัดลอกโค้ดออกไปมากแค่ไหน?
เลือกใช้ request snippet เดียว (cURL, fetch, requests.get ธรรมดา) เมื่อคุณกำลังทำสิ่งเดียว เช่น การดีบักว่าทำไม endpoint คืนค่า 403, การแชร์การเรียกที่สามารถทำซ้ำได้ในตั๋ว, การตรวจสอบอย่างรวดเร็วในเทอร์มินัล, หรือการวางตัวอย่างลงในเอกสารของคุณเอง มันเป็นโค้ดแบบครบวงจรและไม่ต้องการโครงสร้างเพิ่มเติม
เอนเอียงไปทางโค้ดสไตล์ business-model ที่สมบูรณ์ยิ่งขึ้น (บล็อก Axios หรือ requests ที่มีส่วนหัว, พารามิเตอร์ และการจัดการการตอบสนองที่จัดวางไว้) เมื่อการเรียกใช้อยู่ภายในตรรกะของแอปพลิเคชันจริง หาก GET /orders จะอยู่ในโมดูลบริการที่ถูกเรียกใช้จากสามที่ คุณต้องการเวอร์ชันที่มีโครงสร้างที่คุณสามารถห่อด้วยฟังก์ชัน เพิ่มการจัดการข้อผิดพลาด และนำกลับมาใช้ใหม่ได้ ตัวสร้างจะให้ทั้งสองรูปแบบขึ้นอยู่กับรูปแบบที่คุณเลือก; จับคู่รูปแบบกับตำแหน่งที่โค้ดจะอยู่
หากคุณกำลังเรียกใช้ endpoint เดียวกันด้วยการยืนยันตัวตนเดียวกันทั่วทั้งโปรเจกต์ มักจะสะอาดกว่าที่จะรวมส่วนที่ใช้ร่วมกันไว้ที่ส่วนกลาง คู่มือของเราเกี่ยวกับ การตั้งค่าพารามิเตอร์ทั่วโลกใน Apidog แสดงวิธีสร้างส่วนหัวและตัวแปรเพียงครั้งเดียว เพื่อให้ทุกการเรียกที่สร้างขึ้นสืบทอดค่าเหล่านั้นแทนที่จะต้องทำซ้ำโทเค็นในแต่ละ snippet
รักษาโค้ดที่สร้างขึ้นให้ถูกต้องด้วยนิสัย spec-first
โค้ดที่สร้างขึ้นจะถูกต้องก็ต่อเมื่อข้อกำหนดเบื้องหลังถูกต้อง เปลี่ยน GET /orders เพื่อเพิ่มพารามิเตอร์คิวรี region และลืมสร้างใหม่ แล้ว snippet ที่คุณคัดลอกไปจะผิดพลาดอย่างเงียบๆ วิธีแก้ไขคือการปฏิบัติต่อข้อกำหนดเป็นสิ่งที่คุณรักษา และโค้ดเป็นผลลัพธ์ที่ได้จากการสร้างใหม่เมื่อจำเป็น โหมด spec-first ของ Apidog ทำให้คำจำกัดความเป็นสิ่งที่มีอำนาจสูงสุด ดังนั้นโค้ดคำขอที่คุณสร้างขึ้นจะสะท้อนถึงสัญญาปัจจุบันเสมอ ไม่ใช่สัญญาที่ล้าสมัย
สำหรับไวยากรณ์ของ snippet เอง เอกสาร MDN เกี่ยวกับ Fetch API เป็นข้อมูลอ้างอิงที่แข็งแกร่งเมื่อคุณต้องการทำความเข้าใจหรือปรับแต่งรูปแบบ JavaScript ที่ Apidog สร้างขึ้น
ทำให้เวิร์กโฟลว์เป็นอัตโนมัติด้วย Apidog CLI
การสร้างโค้ดเป็นขั้นตอนใน GUI; คุณคัดลอก snippet จากแผง และไม่มีคำสั่ง CLI แยกต่างหากที่สร้างโค้ดไคลเอ็นต์ สิ่งที่ Apidog CLI ทำได้ดีคือการรักษาสองสิ่งรอบๆ ที่การสร้างโค้ดขึ้นอยู่กับ: ข้อกำหนดที่ทันสมัยและชุดการทดสอบที่ผ่านซึ่งพิสูจน์ว่าไคลเอ็นต์ที่สร้างขึ้นทำงานได้จริง
ติดตั้งด้วย npm install -g apidog-cli (Node.js v16+) และตรวจสอบสิทธิ์:
apidog login --with-token <YOUR_ACCESS_TOKEN>
นำเข้าการเปลี่ยนแปลงข้อกำหนดใหม่เพื่อให้โค้ดที่คุณสร้างยังคงเป็นปัจจุบัน และรันสถานการณ์ทดสอบที่บันทึกไว้ซึ่งใช้ endpoint ที่ไคลเอ็นต์ของคุณเรียกใช้:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
ในที่นี้ -t คือ ID สถานการณ์ทดสอบ, -e คือ ID สภาพแวดล้อม และ -r คือผู้รายงาน (cli, html, หรือ junit) เชื่อมโยงสิ่งนี้เข้ากับ pipeline ของคุณตามที่คู่มือ Apidog CLI GitHub Actions ของเราอธิบายไว้ และทุกการ push จะยืนยันว่า GET /orders ยังคงทำงานตามที่ข้อกำหนดสัญญาไว้ ก่อนที่ใครจะสร้างไคลเอ็นต์จากมันใหม่ CLI ไม่ได้เขียนโค้ดไคลเอ็นต์ของคุณ แต่มันช่วยป้องกันสัญญาที่โค้ดนั้นสร้างขึ้น
คำถามที่พบบ่อย
โค้ดที่สร้างขึ้นมี API key และโทเค็นของฉันรวมอยู่ด้วยหรือไม่?
ไม่เป็นค่าเริ่มต้น โค้ดที่สร้างขึ้นจากข้อกำหนด API เพียงอย่างเดียวจะรวมเฉพาะข้อกำหนดเท่านั้น ไม่ใช่ค่าพารามิเตอร์จริงหรือการอนุญาต หากต้องการรับ snippet ที่มีโทเค็นและค่าจริงของคุณ ให้ส่งคำขอก่อน จากนั้นอ่านโค้ดจากแท็บ Actual Request ปฏิบัติต่อโทเค็นใดๆ ใน snippet นั้นว่าเป็นความลับ
Apidog สามารถสร้างโค้ดสำหรับภาษาและไลบรารีใดได้บ้าง?
มีชุดที่หลากหลาย Shell (cURL, Httpie, wget, PowerShell), JavaScript (Fetch, Axios, jQuery, XHR และอื่นๆ), Python (http.client และ Requests), Java (Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R และอื่นๆ คุณเลือกภาษาและรูปแบบเฉพาะในแผงตัวสร้าง
ทำไมฉันไม่เห็นตัวเลือก Auto-generate สำหรับ request bodies?
ตัวเลือกเหล่านั้นต้องใช้ Apidog 2.7.0 หรือใหม่กว่า อัปเดตแอปแล้วตัวเลือกเหล่านั้นจะปรากฏในแท็บ Run เมื่อคุณสร้างเนื้อหา JSON หรือ XML เมื่อพร้อมใช้งาน เมนูดรอปดาวน์ Auto-generate จะมีตัวเลือก Examples และ Generate Each Time พร้อมตัวเลือกย่อยสำหรับการกำหนดค่าวิธีสร้างค่า
การสร้างโค้ดไคลเอ็นต์เป็นฟีเจอร์ที่ต้องชำระเงินหรือไม่?
เอกสารของ Apidog ไม่ได้แยกแยะระหว่างฟรีกับเสียเงิน หรือคลาวด์กับโฮสต์เองสำหรับการสร้างโค้ดไคลเอ็นต์ ข้อกำหนดเวอร์ชันเดียวที่กล่าวถึงคือตัวเลือก Auto-generate สำหรับเนื้อหาคำขอต้องการเวอร์ชัน 2.7.0 หรือใหม่กว่า คุณสามารถ ดาวน์โหลด Apidog และลองใช้ตัวสร้างได้โดยไม่ต้องมีแผนชำระเงิน
ฉันจะแน่ใจได้อย่างไรว่าการเรียกที่สร้างขึ้นใช้งานได้จริง?
สร้าง snippet จากนั้นตรวจสอบ endpoint ด้วยการทดสอบที่บันทึกไว้ คำแนะนำของเราเกี่ยวกับการ เขียนสถานการณ์ทดสอบด้วย Apidog แสดงวิธีสร้าง และ CLI สามารถรันใน CI ได้ ดังนั้นหากมีสัญญาที่เสียหายจะทำให้ build ล้มเหลวก่อนที่คุณจะสร้างไคลเอ็นต์ใหม่จากมัน
สรุป
การสร้างโค้ดไคลเอ็นต์ใน Apidog เปลี่ยนข้อกำหนด endpoint ให้เป็น request ที่พร้อมวางในภาษาใดก็ได้ที่คุณใช้ และแท็บ Actual Request คือเคล็ดลับในการนำค่าจริงและการยืนยันตัวตนเข้าสู่ snippet นั้น แทนที่จะเป็นเทมเพลตว่างๆ รักษาข้อกำหนดให้เป็นแหล่งอ้างอิงหลัก สร้างใหม่เมื่อมีการเปลี่ยนแปลง และให้การทดสอบที่บันทึกไว้ยืนยันว่าการเรียกยังคงทำงานอยู่ ดาวน์โหลด Apidog เพื่อทำตาม, กำหนด endpoint GET /orders ของคุณ, และคัดลอกการเรียกไคลเอ็นต์ที่ใช้งานได้ในไม่กี่คลิก