วิธีสร้าง Client Code จาก API Spec ของคุณใน Apidog

คุณมี endpoint ที่กำหนดไว้แล้วและต้องการเรียกใช้จากแอปของคุณ ส่วนที่มักเสียเวลาคือการแปลข้อกำหนดให้เป็นโค้ดที่ใช้งานได้จริง: URL, headers, โทเค็นยืนยันตัวตน และ query string หากคัดลอกผิดเพียงตัวเดียว คุณอาจต้องไล่หาสาเหตุของ 401 อยู่หลายนาที

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

คุณไม่จำเป็นต้องเขียน boilerplate เหล่านี้ด้วยมือ หากออกแบบ API ไว้ใน Apidog คุณสามารถสร้าง request snippet พร้อมใช้สำหรับ cURL, Python requests, JavaScript fetch, Axios และรูปแบบอื่น ๆ ได้จาก endpoint โดยตรง

แนวทางนี้ยึดข้อกำหนด API เป็นแหล่งความจริงเดียว เช่นเดียวกับหลักการของ OpenAPI Specification กำหนดสัญญาให้ถูกต้องเพียงครั้งเดียว แล้วสร้างโค้ดคำขอจากสัญญานั้น

ตัวสร้างโค้ดไคลเอ็นต์ทำอะไรบ้าง

Apidog แปลงคำจำกัดความ endpoint เป็น request snippet ตามภาษาและไลบรารีที่เลือก ตัวอย่างเช่น เลือก GET /orders แล้วเลือก Python + Requests ระบบจะสร้างโค้ดเรียก endpoint พร้อม headers และพารามิเตอร์ตามที่ระบุไว้ในข้อกำหนด

ฟีเจอร์นี้สร้าง โค้ดคำขอสำหรับ endpoint ไม่ใช่ SDK เต็มรูปแบบหรือแพ็กเกจ client library แบบมีเวอร์ชัน ดังนั้นคุณจะได้สิ่งอย่าง:

• คำสั่ง cURL สำหรับทดสอบในเทอร์มินัล
• requests.get(...) สำหรับสคริปต์ Python
• fetch(...) หรือ Axios สำหรับ JavaScript
• Snippet สำหรับภาษาและ HTTP client อื่น ๆ

แนวทางนี้เข้ากับเวิร์กโฟลว์ การพัฒนา API แบบ Design-first โดยตรง: กำหนดสัญญา สร้างคำขอจากสัญญา และให้ทุกคนใช้อ้างอิงเดียวกัน

สองวิธีในการเปิดตัวสร้างโค้ด

Apidog มีจุดเข้าถึงตัวสร้างโค้ด 2 แห่ง

วิธีที่ 1: จาก Documentation

1. เปิด API หรือ endpoint ที่ต้องการ
2. ไปที่แท็บ Documentation
3. คลิก Generate Client Code
4. เลือกภาษาและรูปแบบ HTTP client

วิธีนี้เหมาะเมื่อคุณกำลังอ่านเอกสารและต้องการนำตัวอย่างไปใช้ทันที

วิธีที่ 2: จาก Run

1. เปิด endpoint ที่ต้องการ
2. ไปที่แท็บ Run
3. คลิกไอคอนโค้ด </>
4. เลือกภาษาและรูปแบบ

วิธีนี้เหมาะเมื่อคุณกำลังทดสอบ request อยู่แล้ว

ทั้งสองวิธีจะเปิดแผงเดียวกัน และสร้าง snippet จาก endpoint เดียวกัน

สร้าง Python client call สำหรับ GET /orders

สมมติว่าคุณมี endpoint นี้:

GET /orders?status=shipped&page=1

Endpoint ใช้แสดงรายการคำสั่งซื้อ โดยรองรับการกรองสถานะและการแบ่งหน้า

ขั้นตอนที่ 1: เลือกภาษาและไลบรารี

เปิด Documentation ของ endpoint แล้วคลิก Generate Client Code

Apidog รองรับรูปแบบต่าง ๆ เช่น:

• 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, C, C#, Objective-C, Ruby, OCaml, Dart, R และ raw HTTP

สำหรับตัวอย่างนี้ ให้เลือก Python และ Requests คุณจะได้โค้ดลักษณะนี้:

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())

คัดลอก snippet ไปวางในสคริปต์ แล้วปรับ URL หรือค่า parameter ตาม environment ที่ใช้งาน

ขั้นตอนที่ 2: เข้าใจข้อจำกัดของ snippet จาก specification

Snippet ที่สร้างจาก API specification จะมีเฉพาะข้อมูลที่นิยามไว้ในสัญญา API เช่น:

• HTTP method
• URL และ path
• Query parameters
• Headers ที่ประกาศไว้
• ตัวอย่างค่าใน specification

แต่จะไม่ใส่ token หรือ credential จริงของคุณโดยอัตโนมัติ เช่น:

Authorization: Bearer <your-real-token>

ดังนั้น snippet ที่สร้างจาก Documentation เหมาะกับการดูโครงสร้าง request หรือ endpoint ที่ไม่ต้องยืนยันตัวตน หาก endpoint มีการป้องกัน ให้สร้างจาก request ที่ส่งจริงแทน

ขั้นตอนที่ 3: ส่ง request ก่อน แล้วใช้ Actual Request

หากต้องการ snippet ที่มีค่าจริง รวมถึง authorization header ให้ทำตามขั้นตอนนี้:

1. ไปที่แท็บ Run
2. กรอก query parameters, headers และ token
3. คลิก Send
4. เปิดแท็บ Actual Request
5. เลื่อนลงไปที่ส่วน client code
6. เลือกภาษาและคัดลอก snippet

ตัวอย่าง Python ที่ได้อาจเป็นแบบนี้:

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())

อย่า commit token จริงลง Git repository ใช้ environment variables หรือ secret manager แทน แนวทางเดียวกับที่ เอกสาร Stripe แนะนำสำหรับ API keys ใช้ได้กับทุก API credential

ตัวอย่างที่ปลอดภัยกว่าคืออ่าน token จาก environment variable:

import os
import requests

url = "https://api.example.com/orders"

querystring = {
    "status": "shipped",
    "page": "1",
}

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['API_TOKEN']}",
}

response = requests.get(url, headers=headers, params=querystring, timeout=15)
response.raise_for_status()

print(response.json())

จัดการ request body สำหรับ POST และ PUT

GET /orders ไม่มี request body แต่ endpoint เช่น POST /orders หรือ PUT /orders/{id} ต้องส่ง body ไปพร้อมคำขอ

ในแท็บ Run คุณสามารถสร้าง body สำหรับ JSON หรือ XML ได้จาก 2 แหล่ง:

1. ตัวอย่าง request body ที่กำหนดใน endpoint specification
2. ปุ่ม Auto-generate สำหรับสร้างข้อมูลตาม schema

เมนู Auto-generate มี 2 โหมดหลัก:

• Examples: เลือกตัวอย่าง body ที่กำหนดไว้
• 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 เมื่อ specification มีตัวอย่างที่พร้อมใช้งานอยู่แล้ว เลือก Use Mock Value เมื่อต้องการข้อมูลจำลองสำหรับทุกฟิลด์

ตัวเลือก Auto-generate สำหรับ request body ต้องใช้ Apidog 2.7.0 หรือใหม่กว่า หากไม่เห็นตัวเลือกนี้ ให้อัปเดตแอปก่อน

Schema ที่มีตัวอย่างชัดเจนจะช่วยลดการแก้ request body ด้วยมือได้มาก โดยเฉพาะหากสร้างจาก เอกสาร API อัตโนมัติด้วย OpenAPI

หากบางค่าต้องเปลี่ยนทุก request เช่น timestamp หรือ order ID แบบสุ่ม ให้ใช้ Insert Dynamic Value หรือไอคอนไม้กายสิทธิ์ข้างช่องพารามิเตอร์ แทนการ hard-code ค่าไว้

หลังเตรียม body แล้ว:

1. คลิก Send
2. เปิด Actual Request
3. คัดลอก snippet ที่มี body, headers และค่าที่ใช้ส่งจริง

เมื่อไหร่ควรใช้ request snippet เทียบกับโค้ดใน application

ใช้ request snippet แบบสั้น เช่น cURL, fetch หรือ requests.get เมื่อคุณต้องการ:

• ดีบัก response เช่น 403 หรือ 401
• แชร์ request ที่ทำซ้ำได้ใน issue หรือ ticket
• ตรวจสอบ endpoint จากเทอร์มินัล
• ใส่ตัวอย่างในเอกสาร
• ทดลอง integration อย่างรวดเร็ว

ตัวอย่าง cURL:

curl --request GET \
  --url 'https://api.example.com/orders?status=shipped&page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_TOKEN"

หาก request อยู่ใน application จริง ให้ห่อ snippet เป็นฟังก์ชันหรือ service module เพื่อให้จัดการ error, timeout และการใช้ซ้ำได้:

import os
import requests


class OrdersClient:
    def __init__(self, base_url: str):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "Accept": "application/json",
            "Authorization": f"Bearer {os.environ['API_TOKEN']}",
        })

    def list_orders(self, status: str, page: int = 1):
        response = self.session.get(
            f"{self.base_url}/orders",
            params={"status": status, "page": page},
            timeout=15,
        )
        response.raise_for_status()
        return response.json()

หากหลาย endpoint ใช้ authentication หรือ headers ชุดเดียวกัน ให้รวมส่วนที่ใช้ร่วมกันไว้ที่เดียว ดูแนวทางในบทความ การตั้งค่าพารามิเตอร์ทั่วโลกใน Apidog

รักษาโค้ดที่สร้างขึ้นให้ถูกต้องด้วยแนวคิด spec-first

โค้ดที่สร้างจะถูกต้องก็ต่อเมื่อ specification ถูกต้อง

ตัวอย่าง: หากเพิ่ม query parameter region ใน GET /orders แต่ยังใช้ snippet เก่า โค้ดในแอปอาจไม่ส่ง parameter ใหม่และเกิดปัญหาแบบเงียบ ๆ

เวิร์กโฟลว์ที่แนะนำ:

1. แก้ไข API specification ก่อน
2. ทดสอบ endpoint ในแท็บ Run
3. สร้าง snippet ใหม่จาก Documentation หรือ Actual Request
4. อัปเดตโค้ดในแอป
5. รัน test scenario เพื่อตรวจสอบ contract

โหมด spec-first ของ Apidog ช่วยให้ definition เป็นแหล่งอ้างอิงหลัก และ snippet ที่สร้างสะท้อนสัญญาปัจจุบัน

สำหรับการทำความเข้าใจหรือปรับแต่ง JavaScript snippet เพิ่มเติม ดู เอกสาร Fetch API ของ MDN

ทำให้เวิร์กโฟลว์เป็นอัตโนมัติด้วย Apidog CLI

การสร้าง client code เป็นขั้นตอนใน GUI: คุณเลือกภาษาแล้วคัดลอก snippet จากแผงโค้ด ไม่มีคำสั่ง CLI แยกสำหรับสร้าง client code โดยตรง

อย่างไรก็ตาม Apidog CLI ช่วยรักษาสิ่งที่ snippet ต้องพึ่งพา ได้แก่ specification ที่อัปเดตและชุดทดสอบที่ยืนยันว่า endpoint ยังทำงานตามสัญญา

ติดตั้ง CLI:

npm install -g apidog-cli

ต้องใช้ Node.js v16+ จากนั้นยืนยันตัวตน:

apidog login --with-token <YOUR_ACCESS_TOKEN>

รัน test scenario ที่บันทึกไว้:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

อาร์กิวเมนต์หลักคือ:

• -t: ID ของ test scenario
• -e: ID ของ environment
• -r: reporter เช่น cli, html หรือ junit

เชื่อมคำสั่งนี้เข้ากับ CI pipeline ตามคู่มือ Apidog CLI GitHub Actions เพื่อให้ทุก push ตรวจสอบว่า endpoint เช่น GET /orders ยังทำงานตาม contract ก่อนนำ snippet ใหม่ไปใช้

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

โค้ดที่สร้างขึ้นมี API key และ token ของฉันหรือไม่?

ไม่ใช่โดยค่าเริ่มต้น Snippet ที่สร้างจาก API specification จะมีเฉพาะข้อมูลใน specification เท่านั้น

หากต้องการโค้ดที่มี token และค่าจริง ให้ส่ง request ในแท็บ Run ก่อน แล้วคัดลอกโค้ดจาก Actual Request อย่าเผยแพร่หรือ commit token ที่อยู่ใน snippet

Apidog สร้างโค้ดสำหรับภาษาและไลบรารีใดได้บ้าง?

รองรับ Shell, JavaScript, Python, Java, Go, PHP, Swift, C, C#, Ruby, Dart, R และอื่น ๆ พร้อมตัวเลือกอย่าง cURL, Fetch, Axios, Requests, OkHttp และ Guzzle

ทำไมไม่เห็น Auto-generate สำหรับ request body?

ฟีเจอร์นี้ต้องใช้ Apidog 2.7.0 หรือใหม่กว่า ให้อัปเดตแอป แล้วเปิดแท็บ Run ของ endpoint ที่มี JSON หรือ XML request body

การสร้าง client code ต้องเสียเงินหรือไม่?

เอกสาร Apidog ไม่ได้ระบุการแยกฟีเจอร์นี้ตามแผนฟรีหรือเสียเงิน ข้อกำหนดเวอร์ชันที่ระบุคือ Auto-generate สำหรับ request body ต้องใช้เวอร์ชัน 2.7.0 หรือใหม่กว่า คุณสามารถ ดาวน์โหลด Apidog เพื่อลองใช้ตัวสร้างโค้ดได้

จะตรวจสอบได้อย่างไรว่าสิ่งที่สร้างใช้งานได้จริง?

สร้าง snippet แล้วตรวจสอบ endpoint ด้วย test scenario ที่บันทึกไว้ ดูคู่มือ การเขียนสถานการณ์ทดสอบด้วย Apidog และรันผ่าน CLI ใน CI เพื่อให้ contract ที่เสียทำให้ build ล้มเหลวก่อนนำโค้ดใหม่ไปใช้

สรุป

Apidog ช่วยแปลง endpoint specification เป็น request snippet ที่พร้อมวางในภาษาและ HTTP client ที่คุณใช้งานจริง

แนวทางที่ใช้งานได้ดีคือ:

1. รักษา API specification ให้ถูกต้อง
2. สร้าง snippet จาก Documentation สำหรับโครงสร้าง request
3. ส่ง request แล้วใช้ Actual Request เมื่อต้องการค่าจริงและ authorization
4. ย้าย secrets ไปไว้ใน environment variables
5. รัน test scenario ผ่าน CI เพื่อยืนยันว่า contract ยังใช้งานได้

ดาวน์โหลด Apidog แล้วลองกำหนด GET /orders ของคุณ จากนั้นสร้าง client call ที่นำไปใช้ได้ในไม่กี่คลิก