ข้ามไปยังเนื้อหาหลัก
เวอร์ชัน: ล่าสุด

Schema API

Schema API ให้การเข้าถึง OpenAPI specification สำหรับ Omise API สิ่งนี้ช่วยให้คุณค้นพบ endpoints ที่มีโดยโปรแกรม เข้าใจโครงสร้าง request/response และเชื่อมต่อกับเครื่องมือเอกสาร API

ภาพรวม​

Schema API ให้:

  • OpenAPI Specification - เอกสาร API ที่สมบูรณ์ในรูปแบบ OpenAPI 3.0
  • Endpoint Discovery - ค้นพบ API endpoints ทั้งหมดที่มีโดยโปรแกรม
  • Data Structures - ข้อกำหนด schema ที่สมบูรณ์สำหรับ request และ response objects ทั้งหมด
  • Validation - ใช้ schema เพื่อตรวจสอบ API requests ก่อนส่ง
  • Code Generation - สร้าง client libraries โดยใช้ OpenAPI code generators

Schema API ทำงานอย่างไร​

  1. ขอ Schema - ส่ง GET request เพื่อดึง OpenAPI specification
  2. แยกวิเคราะห์ Response - Response เป็นเอกสาร OpenAPI 3.0 ที่สมบูรณ์ในรูปแบบ JSON
  3. ใช้ Schema - นำเข้าไปยังเครื่องมือเช่น Swagger UI, Postman หรือ code generators
  4. อัปเดตอยู่เสมอ - Schema สะท้อนสถานะปัจจุบันของ API

กรณีการใช้งาน​

เอกสาร API​

สร้างเอกสาร API แบบโต้ตอบโดยใช้เครื่องมือเช่น Swagger UI หรือ ReDoc

การสร้าง Client​

ใช้ OpenAPI code generators เพื่อสร้าง client libraries ที่ type-safe ในภาษาที่คุณต้องการ

การตรวจสอบ Request​

ตรวจสอบ API requests กับ schema ก่อนส่งเพื่อจับข้อผิดพลาดตั้งแต่เนิ่นๆ

การเชื่อมต่อ IDE​

นำเข้า schema ไปยัง IDE ของคุณสำหรับ autocomplete และ type checking

การทดสอบ API​

สร้าง test cases ตามข้อกำหนด schema

Endpoints ที่มี​

รูปแบบ Schema​

Schema ให้ในรูปแบบ OpenAPI 3.0 และรวมถึง:

Paths​

API endpoints ทั้งหมดที่มีพร้อม:

  • HTTP methods (GET, POST, PATCH, DELETE)
  • Request parameters (path, query, body)
  • Response structures สำหรับแต่ละ status code
  • ข้อกำหนดการยืนยันตัวตน

Components​

ข้อกำหนด schema ที่ใช้ซ้ำได้สำหรับ:

  • Request bodies
  • Response objects
  • Common parameters
  • Security schemes

Security​

ข้อกำหนดการยืนยันตัวตน:

  • HTTP Basic Auth ด้วย API keys
  • ข้อกำหนด Public key vs Secret key

ตัวอย่างการเชื่อมต่อ​

Swagger UI​

<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
  SwaggerUIBundle({
    url: "https://api.omise.co/schema",
    dom_id: '#swagger-ui'
  });
</script>

Postman​

  1. เปิด Postman
  2. คลิก Import
  3. ป้อน URL: https://api.omise.co/schema
  4. Import เป็น OpenAPI 3.0

OpenAPI Generator​

# สร้าง Python client
openapi-generator generate \
  -i https://api.omise.co/schema \
  -g python \
  -o ./omise-python-client

แนวทางปฏิบัติที่ดี​

ควรทำ​

  • Cache schema - Schema ไม่เปลี่ยนแปลงบ่อย cache ไว้ในเครื่อง
  • จัดการเวอร์ชันการเชื่อมต่อ - กำหนดเวอร์ชัน schema เฉพาะเมื่อมี
  • ตรวจสอบแต่เนิ่นๆ - ใช้ schema validation เพื่อจับข้อผิดพลาดก่อน API calls
  • สร้าง clients - ใช้ code generators สำหรับ type safety และประสิทธิภาพ
  • อัปเดตเครื่องมือ - ตรวจสอบให้แน่ใจว่า OpenAPI tools ของคุณรองรับ spec ล่าสุด

ไม่ควรทำ​

  • อย่า hardcode structures - ใช้ schema สำหรับการเชื่อมต่อแบบ dynamic
  • อย่าละเลยการอัปเดต - ตรวจสอบการอัปเดต schema เป็นระยะ
  • อย่าข้ามการตรวจสอบ - ตรวจสอบกับ schema เสมอในการพัฒนา

แหล่งข้อมูลที่เกี่ยวข้อง​

ต้องการความช่วยเหลือ? ติดต่อ support@omise.co