การใช้ SmartDocs เพื่อจัดเก็บ API

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X ข้อมูล

Smartdocs ช่วยให้คุณบันทึก API ในพอร์ทัลนักพัฒนาซอฟต์แวร์ Drupal 7 ในลักษณะที่ทำให้เอกสารประกอบของ API โต้ตอบได้อย่างเต็มที่ เอกสารแบบอินเทอร์แอกทีฟช่วยให้ผู้ใช้พอร์ทัลดำเนินการต่อไปนี้ได้

• อ่านเกี่ยวกับ API
• ส่งคำขอแบบเรียลไทม์ไปยัง API ของคุณ
• ดูการตอบกลับแบบเรียลไทม์ที่ส่งคืนจาก API

การสร้างเอกสารประกอบแบบอินเทอร์แอกทีฟใน API ช่วยให้ผู้ใช้พอร์ทัลเรียนรู้ ทดสอบ และประเมิน API ได้อย่างง่ายดาย

Edge Management API คือ RESTful API ที่ช่วยให้คุณเข้าถึงบริการ API โดยใช้ไคลเอ็นต์ HTTP ใดก็ได้ Apigee คือ SmartDocuments เพื่อสร้างเอกสารประกอบแบบอินเทอร์แอกทีฟสำหรับ Edge Management API ดูเอกสารประกอบเกี่ยวกับ API ได้ที่นี่

ตัวอย่างพอร์ทัล SmartDocs

คุณต้องมีพอร์ทัลบริการสำหรับนักพัฒนาซอฟต์แวร์ Apigee จึงจะใช้ SmartDocuments ได้ ดูข้อมูลเพิ่มเติมได้ที่การสร้างพอร์ทัลนักพัฒนาซอฟต์แวร์

จากหน้าแรกของพอร์ทัลนักพัฒนาซอฟต์แวร์ ให้คลิก API ในแถบนำทางด้านบนเพื่อดูหน้าเอกสารประกอบของ API

พอร์ทัลมี API อยู่ 2 รายการ ได้แก่ Hello World และ Pet Store Example

Hello World API สร้างขึ้นจากการจำลองข้อกำหนดของ OpenAPI เป้าหมาย mocktarget.yaml ดูข้อมูลเพิ่มเติมได้ที่ https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi

Pet Store Example API สร้างขึ้นจากการสาธิตร้านขายสัตว์เลี้ยงแบบคลาสสิก

สำรวจ Hello World API

1. คลิก Hello World API หน้าสรุป Hello World API จะปรากฏขึ้น
   
2. คลิกดูการยืนยัน API SmartDocuments สำหรับทรัพยากรนี้จะปรากฏขึ้น:
   
3. คลิกส่งคำขอนี้
4. ดูการตอบกลับที่ตอบกลับ:

   HTTP/1.1 200 OK
   Connection:
   keep-alive
   Content-Length:
   18
   Content-Type:
   text/html; charset=utf-8
   Date:
   Tue, 21 Jun 2016 21:49:32 GMT
   ETag:
   W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
   X-Powered-By:
   Apigee
   <H2>I <3 APIs</H2>
   

5. คลิกแท็บคำขอเพื่อดูคำขอ หรือแท็บ cURL เพื่อดูการเรียก cURL ที่เกี่ยวข้อง

วิธีการจัดทำเอกสารสำหรับ API โดยใช้ SmartGoogle

Smartdocument แสดง API ของคุณโดยใช้model ซึ่งโมเดลมีข้อมูลทั้งหมดเกี่ยวกับ API ของคุณ พอร์ทัลจะดึงข้อมูลเกี่ยวกับ API ของคุณจากโมเดลเพื่อแสดงหน้าเอกสารประกอบในพอร์ทัลเป็นโหนด Drupal โดยที่โหนด Drupal แต่ละรายการจะสอดคล้องกับหน้าเอกสารประกอบในพอร์ทัล

ขั้นตอนทั่วไปที่คุณปฏิบัติตามเพื่อใช้งาน SmartDocs มีดังนี้

1. กำหนดค่าโมดูล Drupal SmartDocs ในพอร์ทัล
2. สร้างโมเดล SmartDocuments
3. เพิ่ม API ลงในโมเดลจากไฟล์ WADL, ข้อมูลจำเพาะของ OpenAPI (เดิมคือ Swคนหนึ่ง) หรือด้วยตนเอง
4. แสดงผลโมเดลเป็นคอลเล็กชันของโหนด Drupal โหนด Drupal แต่ละโหนดมีข้อมูลเกี่ยวกับ API รายการเดียว เช่น หากทรัพยากรใน API รองรับทั้งคำขอ POST และ PUT เอกสารอัจฉริยะจะสร้างโหนด Drupal แยกต่างหากสำหรับ POST และ PUT
5. เผยแพร่โหนด Drupal เมื่อเผยแพร่แล้ว ผู้ใช้พอร์ทัลจะดูและโต้ตอบกับ API ของคุณได้
6. แก้ไขโหนด Drupal ก่อนหรือหลังเผยแพร่ คุณแก้ไขโหนด Drupal ได้โดยใช้ตัวแก้ไข Drupal หรือแก้ไขไฟล์ WADL ต้นฉบับหรือข้อกำหนด OpenAPI เมื่อแก้ไขไฟล์ WADL หรือข้อกำหนด OpenAPI เสร็จแล้ว ให้นำเข้าไฟล์กลับไปยังโมเดลเป็นการแก้ไขใหม่ จากนั้นแสดงผลและเผยแพร่การเปลี่ยนแปลง
7. เปิดใช้ TLS เนื่องจาก SmartDocuments สามารถส่งข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ไปยังแบ็กเอนด์ ซึ่งเป็นส่วนหนึ่งของการส่งคำขอไปยัง API ของคุณ คุณจึงควรเปิดใช้ TLS ในพอร์ทัลของคุณเพื่อให้มั่นใจว่าข้อมูลเข้าสู่ระบบเหล่านั้นมีความปลอดภัย ในสภาพแวดล้อมการใช้งานจริงและการทดสอบของพอร์ทัล Apigee คือใบรับรอง TLS ที่จำเป็นต่อการส่งคำขอ https:// อย่างไรก็ตาม ก่อนที่คุณจะเผยแพร่พอร์ทัลของตนเอง คุณจะต้องรับใบรับรอง TLS ของตัวเองและเปิดใช้ TLS ดูข้อมูลเพิ่มเติมได้ที่การใช้ TLS ในพอร์ทัล

เกี่ยวกับโมเดลและเทมเพลต SmartDoc

เมื่อสร้างโมเดลในพอร์ทัล โมเดลนั้นจริงๆ แล้วจะเก็บอยู่ในองค์กร Edge ไม่ใช่ใน Drupal โมเดลคือบล็อกขนาดใหญ่ของ JSON ที่มีชื่อภายใน (เช่น "my-smartdocs-api") และโมเดลเป็นตัวกำหนดโครงสร้างของ API ในทางกลับกัน พอร์ทัลจะแสดงผลโมเดลใน HTML และมีอินเทอร์เฟซการแก้ไขสำหรับโมเดล ระบบจะพุชการอัปเดต API ในพอร์ทัลกลับไปยังโมเดลต้นทางโดยอัตโนมัติ

สมมติว่าคุณมีพอร์ทัลหลายพอร์ทัลในองค์กร (เช่น การพัฒนา พื้นที่งาน และเวอร์ชันที่ใช้งานจริง) ใน Pantheon คุณสามารถย้ายพอร์ทัลจากสภาพแวดล้อมหนึ่งไปยังอีกสภาพแวดล้อมหนึ่งได้ อินสแตนซ์แต่ละรายการของพอร์ทัลดูเหมือนว่าจะมีโมเดลของตัวเอง แต่อินสแตนซ์ทั้งหมดอ้างอิงโมเดลต้นทางจริงๆ หากคุณแก้ไข API ใน dev โมเดลจะอัปเดตและการเปลี่ยนแปลงจะปรากฏในเวอร์ชันที่ใช้งานจริง ในทำนองเดียวกัน หากคุณลบโมเดลใน dev ระบบจะลบต้นทางออกและโมเดลจะใช้ในเวอร์ชันที่ใช้งานจริงไม่ได้อีกต่อไป

เทมเพลตจะควบคุมรูปลักษณ์ของ SmartDocs และเทมเพลตเหล่านั้น (ควบคุมโดยเครื่องจัดการและไฟล์ CSS) จะเก็บอยู่กับอินสแตนซ์ของพอร์ทัลแต่ละรายการ ดังนั้น แต่ละพอร์ทัลจึงสามารถใช้เทมเพลตที่ไม่ซ้ำกัน สำหรับแต่ละโมเดลได้ทางทฤษฎี อย่างไรก็ตาม ความสะดวกอย่างหนึ่งของเฟรมเวิร์กการแสดงผลคือจะมีการนำเทมเพลตเริ่มต้น (ค่าเริ่มต้นของ Apigee หรือเทมเพลตที่คุณระบุ) ไปใช้กับแต่ละโมเดลโดยอัตโนมัติ

แผนภาพต่อไปนี้แสดงความสัมพันธ์ระหว่างโมเดลและพอร์ทัล ลูกศรสีเขียวจะแสดงการซิงค์อัตโนมัติ

คำสั่ง cURL ต่อไปนี้จะแสดงโมเดลทั้งหมดในองค์กรของคุณ

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

การกำหนดค่าโมดูล SmartDocuments

Apigee ได้ติดตั้งใช้งาน SmartDocuments เป็นโมดูล Drupal ที่กำหนดเอง ใช้ขั้นตอนต่อไปนี้เพื่อกำหนดค่าโมดูล SmartDocs

วิธีกำหนดค่าโมดูล SmartGoogle

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือกโมดูลในเมนูการดูแลระบบ Drupal รายการโมดูล Drupal ที่ติดตั้งทั้งหมดจะปรากฏขึ้น
3. เปิดใช้โมดูล SmartDocs
4. บันทึกการกำหนดค่า
5. เลือกโมดูลในเมนูผู้ดูแลระบบ Drupal
6. เลือก SmartDocs -> สิทธิ์ และตรวจสอบว่าเปิดใช้ "ดำเนินงานการดูแลระบบสำหรับโมดูล SmartDocuments" สำหรับบทบาท "ผู้ดูแลระบบ" ไว้
7. เลือกการกำหนดค่า > พอร์ทัลนักพัฒนาซอฟต์แวร์ ในเมนูการดูแลระบบ Drupal
8. ตั้งค่า ระยะหมดเวลาของการเชื่อมต่อ และ ระยะหมดเวลาของคำขอ เป็น 16 วินาที
9. บันทึกการกำหนดค่า
10. กำหนดการตั้งค่า URL ดังนี้
    1. เลือกการกำหนดค่า > การค้นหาและข้อมูลเมตา > ชื่อแทน URL > การตั้งค่าจากเมนู Drupal
    2. ตั้งค่าความยาวสูงสุดของชื่อแทนและความยาวสูงสุดของคอมโพเนนต์เป็น 255
    3. ขยายเครื่องหมายวรรคตอน
    4. สำหรับการตั้งค่าวงเล็บปีกกาซ้าย ({) และวงเล็บปีกกาขวา (}) ให้เลือกไม่มีการดำเนินการ (อย่าแทนที่)
    5. คลิก Save Configuration
11. หากพอร์ทัลนักพัฒนาซอฟต์แวร์แสดงต่อผู้ใช้ในเครือข่ายภายในโดยไม่สามารถเข้าถึงอินเทอร์เน็ต หรือหากชุดย่อยของ API อยู่ในเครือข่ายส่วนตัว ให้กำหนดค่า URL พร็อกซีของ SmartGoogle API ดังนี้
    1. เลือก Configuration > SmartDocument ในเมนู Drupal
    2. ขยายการตั้งค่าขั้นสูง
    3. อัปเดตช่อง URL พร็อกซีของ SmartGoogle ดังนี้ <host>/smartdocs/v1/sendrequest
       ความช่วยเหลือในบรรทัดควรระบุค่าที่จำเป็นสำหรับสภาพแวดล้อมของคุณ ตัวอย่างเช่น
       https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest
       
       ช่องนี้จะมีค่าเริ่มต้นเป็น https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. คลิก Save Configuration

กำลังสร้างโมเดล

โมเดลประกอบด้วยข้อมูลทั้งหมดเกี่ยวกับการนำเสนอ API ของคุณ คุณอาจกำหนดโมเดลหลายโมเดลบนพอร์ทัลเพื่อรองรับ API ต่างๆ หรือจัดกลุ่ม API ทั้งหมดไว้ในโมเดลเดียวก็ได้

แต่ละโมเดลจะระบุชื่อภายในที่ไม่ซ้ำกันซึ่งกำหนด URL ฐานของโหนด Drupal ที่สร้างขึ้น URL ของโหนด Drupal แต่ละรายการอยู่ในรูปแบบต่อไปนี้

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

ที่ไหน

• drupalBasePath: URL ฐานของพอร์ทัล
• internalName: ชื่อภายในของโมเดล
• httpMethod: เมธอด HTTP ของ API เช่น get,put, post หรือลบ
• resourcePath: เส้นทางทรัพยากร

เช่น หากระบุชื่อภายในเป็น "mymodel" URL ของโหนด Drupal ที่สร้างขึ้นสำหรับคำขอ GET ที่ส่งไปยังทรัพยากรชื่อ "/books" จะเป็นดังนี้

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

วิธีสร้างโมเดล

เมื่อสร้างโมเดล ระบบจะจัดเก็บโมเดลนั้นในองค์กร Edge ของคุณเป็นต้นทางสำหรับโครงสร้าง API ดูข้อมูลเพิ่มเติมได้ที่เกี่ยวกับรุ่นและเทมเพลต SmartDoc

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือกเนื้อหา > SmartDocs ในเมนูการดูแลระบบ Drupal
3. เลือกรูปแบบใหม่ที่ด้านบนของหน้า
4. ป้อนข้อมูลในช่องต่อไปนี้
   • ชื่อ: ชื่อโมเดลที่จะแสดงทั่วทั้งเว็บไซต์
   • ชื่อภายใน: ขณะที่คุณพิมพ์ชื่อ ชื่อภายในจะปรากฏขึ้น ชื่อภายในสำหรับโมเดลที่ต้องไม่ซ้ำกันในโมเดลทั้งหมด ชื่อภายในต้องมีเฉพาะตัวอักษรพิมพ์เล็ก ตัวเลข และขีดกลางเท่านั้นโดยไม่มีช่องว่าง เลือกแก้ไขเพื่อแก้ไขชื่อนี้
   • คำอธิบาย: คำอธิบายโมเดล
5. เลือกสร้างโมเดล

หลังจากสร้างโมเดลแล้ว ระบบจะเปลี่ยนเส้นทางคุณไปยังหน้าของโมเดล จากตรงนั้น คุณสามารถใช้เมนูแบบเลื่อนลง การดำเนินการ bx เพื่อทำสิ่งต่อไปนี้

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

การเพิ่ม API ไปยังโมเดล

คุณเพิ่ม API ไปยังโมเดลได้โดยทำดังนี้

• การนำเข้าไฟล์ WADL ที่มีคำจำกัดความของ API
• การนำเข้าข้อกำหนดของ OpenAPI (OpenAPI 2.0 หรือ 1.2)
• การสร้างทรัพยากรและวิธีการด้วยตนเอง

คุณจะนำเข้าไฟล์ JSON ของ SmartGoogle ไปยังโมเดลได้ด้วย โดยปกติแล้ว ไฟล์นี้สร้างขึ้นโดยการส่งออกโมเดลที่มีอยู่ก่อน แก้ไขไฟล์ แล้วนำเข้าการอัปเดต ดูข้อมูลเพิ่มเติมได้ใน "การส่งออกและการนำเข้าโมเดล" ด้านล่าง

นำเข้า WADL

หลังจากสร้างโมเดลสำเร็จแล้ว ให้นำเข้าไฟล์ WADL ที่อธิบาย API ของคุณ ทุกครั้งที่นำเข้าไฟล์ WADL คุณจะสร้างการแก้ไขใหม่ของโมเดลโดยอัตโนมัติ

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือกเนื้อหา > SmartDocs ในเมนูการดูแลระบบ Drupal
3. เลือกรูปแบบที่ต้องการอัปเดต
4. ในส่วนการดำเนินการ ให้เลือกนำเข้า
5. เลือก WADL ในรายการแบบเลื่อนลง เลือกรูปแบบ ในหน้าการนำเข้า SmartDocument
6. เลือกไฟล์หรือ URL ในรายการแบบเลื่อนลงประเภทการอัปโหลด
   1. หากเลือกไฟล์ ให้เรียกดูไฟล์ WADL
   2. หากคุณเลือก URL ให้ระบุ URL ของไฟล์ WADL
7. คลิกนำเข้าเพื่อนำเข้าโมเดล ตอนนี้คุณแสดงผลโมเดลได้แล้ว
8. ระบบจะเปลี่ยนเส้นทางคุณไปยังหน้าข้อมูลของโมเดล ซึ่งคุณจะแสดงผลโมเดลได้แล้ว

นำเข้าข้อมูลจำเพาะของ OpenAPI

หลังจากสร้างโมเดลสำเร็จแล้ว คุณจะนำเข้าข้อมูลจำเพาะของ OpenAPI (เดิมคือ Swคนหนึ่ง) ได้ Edge รองรับ OpenAPI เวอร์ชัน 1.2 และ 2.0

OpenAPI ใช้ไฟล์ที่มีออบเจ็กต์ JSON เพื่ออธิบาย API ทุกครั้งที่นำเข้าข้อมูลจำเพาะของ OpenAPI คุณจะสร้างการแก้ไขใหม่ของโมเดลโดยอัตโนมัติ

หากต้องการนำเข้าข้อกำหนดของ OpenAPI ให้ทำดังนี้

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก เนื้อหา > SmartDocument ในเมนูการดูแลระบบ Drupal
3. เลือกรูปแบบที่ต้องการอัปเดต
4. ในส่วนการดำเนินการ ให้เลือกนำเข้า
5. เลือก Swurge JSON หรือ Swคนหนึ่ง YAML ใน เมนูแบบเลื่อนลงเลือกรูปแบบในหน้าการนำเข้าของ SmartDocument
6. เลือกไฟล์หรือ URL ในรายการแบบเลื่อนลงประเภทการอัปโหลด (คุณต้องเลือก URL สำหรับ OpenAPI 1.2)
   1. หากคุณเลือกไฟล์ ให้เรียกดูข้อกำหนดของ OpenAPI
   2. หากคุณเลือก URL ให้ระบุ URL ของข้อกำหนดของ OpenAPI
7. คลิกนำเข้าเพื่อนำเข้าโมเดล
8. ระบบจะเปลี่ยนเส้นทางคุณไปยังหน้าข้อมูลของโมเดล ซึ่งคุณจะแสดงผลโมเดลได้แล้ว

สร้างทรัพยากรและวิธีการด้วยตนเอง

หากไม่มีไฟล์ WADL หรือข้อกำหนด OpenAPI ที่แสดงถึง API ของคุณ คุณจะเพิ่ม API ลงในโมเดลด้วยตนเองได้ นอกจากนี้ หากคุณใช้ไฟล์ WADL หรือข้อกำหนด OpenAPI เพื่อสร้างโมเดล คุณจะใช้กระบวนการนี้เพื่อแก้ไข API ซึ่งรวมถึงการเพิ่ม API ใหม่หลังจากนำเข้าได้

วิธีเพิ่ม API ด้วยตนเอง

1. สร้างการแก้ไขใหม่ของโมเดล
   
   เมื่อสร้างการแก้ไข คุณจะระบุเส้นทางฐานเดียวของ API ทั้งหมดในโมเดล ซึ่งหมายความว่า API ทั้งหมดในโมเดลจะใช้เส้นทางฐานเดียวกัน ตัวอย่างเช่น ระบุเส้นทางฐานเป็น
   
   https://myCompany.com/v1
   
   เมื่อเพิ่มทรัพยากรลงในโมเดล ทรัพยากรดังกล่าวจะขยายเส้นทางฐาน
2. กำหนดทรัพยากรอย่างน้อย 1 รายการสำหรับโมเดล เส้นทางทรัพยากรจะรวมเข้ากับเส้นทางฐานของการแก้ไขโมเดลเพื่อระบุ URL แบบเต็มของทรัพยากร เช่น หากทรัพยากรกำหนดเส้นทางของ "/login" URL แบบเต็มของทรัพยากรจะเป็น
   
   https://myCompany.com/v1/login
3. กำหนดเมธอดอย่างน้อย 1 วิธีสำหรับแต่ละทรัพยากร เมธอดจะระบุคำกริยา HTTP ที่เรียกใช้ในทรัพยากรได้ เช่น สำหรับทรัพยากร "/login" คุณรองรับ POST สำหรับการเข้าสู่ระบบและ DELETE สำหรับการออกจากระบบ ทรัพยากรนี้ไม่รองรับคำกริยา HTTP อื่นๆ เช่น PUT หรือ GET ดังนั้น ให้ระบุ 2 เมธอดสำหรับทรัพยากร หนึ่งวิธีสำหรับ POST และอีกวิธีสำหรับ DELETE
   
   เมธอดใช้ URL ของทรัพยากรจากทรัพยากรระดับบนสุด ดังนั้น เมธอดทั้งหมดที่มี URL เดียวกันจะได้รับการกำหนดภายใต้ทรัพยากรเดียวใน SmartDocuments

ตามกฎทั่วไปมีดังนี้

• สร้างโมเดล SmartDocuments ที่ต่างกันสำหรับแต่ละเส้นทางฐานที่ไม่ซ้ำกันใน API ของคุณ
• กำหนดทรัพยากร SmartDocs ที่ต่างกันสำหรับทรัพยากรแต่ละรายการที่ไม่ซ้ำกันใน API
• กำหนดเมธอด SmartDocuments แบบต่างๆ สำหรับคำกริยา HTTP ที่ทรัพยากรรองรับ

การสร้างการแก้ไขใหม่ของโมเดล

คุณสามารถเพิ่มทรัพยากรในการแก้ไขโมเดลที่มีอยู่ได้เท่านั้น หากโมเดลมีการแก้ไขอยู่แล้ว คุณจะเพิ่มทรัพยากรได้ หากโมเดลใหม่และไม่มีการแก้ไข ให้สร้างการแก้ไขใหม่

ในการสร้างโมเดลการแก้ไขใหม่:

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก เนื้อหา > SmartDocs ในเมนูการดูแลระบบ Drupal
3. สำหรับโมเดลที่คุณต้องการอัปเดต ให้เลือกเพิ่ม การแก้ไขในส่วนการดำเนินการ
4. ในหน้าเพิ่มการแก้ไข API ให้ป้อนข้อมูลต่อไปนี้
   • ชื่อที่แสดง: ชื่อของการแก้ไขตามที่ปรากฏในพอร์ทัล
   • รหัสเวอร์ชัน: ตัวระบุสั้นๆ สำหรับการแก้ไข
   • คำอธิบาย: คำอธิบายการแก้ไข
   • URL ฐาน: URL ฐานของ API ทั้งหมดในการแก้ไขโมเดล โมเดลใช้ URL ฐานที่แตกต่างกันสำหรับการแก้ไขแต่ละครั้งได้ เช่น คุณใส่ตัวระบุเวอร์ชันใน URL พื้นฐาน สําหรับการแก้ไขโมเดลแรก URL ฐานคือ
     https://myCompany.com/v1
     สําหรับการแก้ไขครั้งถัดไป URL พื้นฐานอาจเป็น:
     https://myCompany.com/v2
5. เลือกเพิ่มการแก้ไข ระบบจะเปลี่ยนเส้นทางคุณไปยังหน้าการแก้ไขของโมเดล ตอนนี้คุณสามารถกำหนดทรัพยากรบนโมเดลได้แล้ว

การกำหนดทรัพยากร

ทรัพยากรระบุ URL แบบเต็มของ API เมื่อกำหนดทรัพยากร คุณจะต้องระบุเส้นทางทรัพยากร ซึ่งรวมกับ URL ฐานในการแก้ไขโมเดลเพื่อสร้าง URL แบบเต็มของทรัพยากร

วิธีกำหนดทรัพยากร

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก เนื้อหา > SmartDocument ในเมนูการดูแลระบบ Drupal
3. สำหรับโมเดลที่คุณต้องการอัปเดต ในส่วนการดำเนินการ ให้เลือกการแก้ไข API เพื่อดูการแก้ไขทั้งหมดของโมเดล
4. เลือกการแก้ไขที่ต้องการแก้ไข
5. ในหน้าการแก้ไข ให้เลือกเพิ่มแหล่งข้อมูลจากเมนูแบบเลื่อนลง
6. ในหน้าเพิ่มทรัพยากร ให้ป้อนข้อมูลต่อไปนี้
   • ชื่อที่แสดง: ชื่อของทรัพยากร
   • เส้นทาง: เส้นทางทรัพยากร เริ่มต้นด้วย "/" ค่าของเส้นทางจะรวมกับ URL ฐานของการแก้ไขโมเดลเพื่อสร้าง URL แบบเต็มของทรัพยากร
   • คำอธิบาย: คำอธิบายของทรัพยากร
   • พารามิเตอร์: ป้อนออบเจ็กต์ JSON ที่กำหนดพารามิเตอร์แต่ละรายการบนทรัพยากร (ไม่บังคับ) พารามิเตอร์เหล่านี้มีอธิบายไว้ด้านล่าง
7. เลือกเพิ่มแหล่งข้อมูล ระบบจะเปลี่ยนเส้นทางคุณไปยังหน้าโมเดล คุณกำหนดเมธอดบนทรัพยากรได้แล้ว

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

หรือจะระบุพารามิเตอร์ของเมธอดก็ได้ เช่น เมธอด POST อาจรองรับพารามิเตอร์การค้นหาที่ใช้กับเมธอด DELETE ไม่ได้ ดังนั้น ให้เพิ่มพารามิเตอร์ที่เจาะจงสำหรับเมธอดเมื่อคุณกำหนดเมธอด ตามที่อธิบายด้านล่าง

รูปภาพต่อไปนี้แสดงหน้า SmartDocs ที่มีอยู่สำหรับ API อนุมัติหรือเพิกถอนแอปของนักพัฒนาซอฟต์แวร์ Apigee โดยไฮไลต์พารามิเตอร์แต่ละประเภทไว้

พารามิเตอร์แต่ละประเภทจะกำหนดโดยออบเจ็กต์ JSON ดังนี้

พารามิเตอร์เทมเพลตจะกำหนดตัวแปรในเส้นทางทรัพยากร เช่น คุณกำหนดพารามิเตอร์เทมเพลต 2 ตัวในทรัพยากร สังเกตว่าคำจำกัดความพารามิเตอร์แต่ละรายการในอาร์เรย์พารามิเตอร์คั่นด้วยเครื่องหมายจุลภาค

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

จากนั้นคุณจะใช้พารามิเตอร์เทมเพลตในคำจำกัดความของเส้นทางทรัพยากรซึ่งอยู่ใน "{}" ได้ ตัวอย่างเช่น กำหนดเส้นทางเป็น

/login/{org_name}/{developer_email}

ในหน้า Smartdocs API ผู้ใช้ต้องแก้ไข URL เพื่อระบุส่วน org_name และ developer_email ของ URL ก่อนส่งคำขอได้

การกำหนดเมธอด

กำหนดเมธอดอย่างน้อย 1 วิธีสำหรับแต่ละทรัพยากร คำจำกัดความของเมธอดจะระบุคำกริยา HTTP ที่เรียกใช้ในทรัพยากรได้ ทรัพยากรอาจกำหนดเมธอดเดียวหรือหลายเมธอดก็ได้

ในการกำหนดเมธอด ให้ระบุพารามิเตอร์ที่เมธอดใช้ รวมถึงพารามิเตอร์ของการค้นหาและส่วนหัว ดูข้อมูลเกี่ยวกับการเพิ่มพารามิเตอร์ในเมธอดในคำอธิบายด้านบน

รูปภาพต่อไปนี้แสดงหน้า SmartDocuments ที่มีอยู่สำหรับ API ของ Apigee Create Developer โดยไฮไลต์แต่ละส่วนของหน้าด้วยค่าที่เกี่ยวข้องซึ่งคุณตั้งค่าไว้เมื่อกำหนดเมธอด

รูปภาพถัดไปแสดงหน้าเดียวกัน แต่เลือกคำอธิบายของเนื้อความคำขอ

วิธีกำหนดเมธอด

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก เนื้อหา > SmartDocs ในเมนูการดูแลระบบ Drupal
3. สำหรับโมเดลที่คุณต้องการอัปเดต ในส่วนการดำเนินการ ให้เลือกการแก้ไข API เพื่อดูการแก้ไขทั้งหมดของโมเดล
4. เลือกการแก้ไขที่ต้องการแก้ไข
5. ในหน้าการแก้ไข ให้เลือกเพิ่มเมธอดจากเมนูแบบเลื่อนลงสำหรับทรัพยากรรายการใดรายการหนึ่ง
6. ในหน้าแก้ไขวิธีการ ให้ป้อนข้อมูลต่อไปนี้
   • ชื่อที่แสดง: ชื่อของ API ซึ่งจะกลายเป็นชื่อหน้า Drupal สำหรับ API ด้วย
   • คำอธิบาย: อธิบาย API
   • Method คำกริยา: ประเภทกริยา HTTP
   • แผนการรักษาความปลอดภัย: ระบุโหมดการตรวจสอบสิทธิ์สำหรับวิธีการนั้นๆ (หากมี) โปรดดูข้อมูลเพิ่มเติมที่การกำหนดค่าประเภทการตรวจสอบสิทธิ์ SmartDocument
   • ประเภทเนื้อหา: ประเภทเนื้อหาของคำขอและการตอบกลับ โปรดดูหัวข้อด้านล่างเกี่ยวกับการกำหนดค่าวิธีการตรวจสอบสิทธิ์แบบต่างๆ
   • พารามิเตอร์: (ไม่บังคับ) พารามิเตอร์ของการค้นหาหรือส่วนหัวสำหรับเมธอด โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับการเพิ่มพารามิเตอร์ไปยังแหล่งข้อมูลด้านบน
   • ขอเอกสารเนื้อความ: (ไม่บังคับ) อธิบายเนื้อความของคำขอ เมธอด POST และ PUT รับเนื้อหาของคำขอ คุณใช้พื้นที่นี้เพื่ออธิบายได้ หากคุณไม่ระบุค่านี้ ลิงก์คำอธิบายในส่วนเนื้อความคำขอจะไม่แสดงในหน้า SmartDocuments ที่สร้างขึ้น
   • ตัวอย่างเนื้อความของคำขอ: (ไม่บังคับ) แสดงตัวอย่างเนื้อหาของคำขอ โดยทั่วไปจะเป็นออบเจ็กต์ JSON หรือเป็น XML สำหรับคำกริยา POST และ PUT ระบบจะส่งตัวอย่างเนื้อหาคำขอเป็นส่วนหนึ่งของคำขอแต่ละรายการ ผู้ใช้หน้า SmartDocs จะแก้ไขตัวอย่างนี้ก่อนส่งคำขอไปยัง API หากคุณไม่ระบุค่านี้ ลิงก์ค่าในส่วนเนื้อความคำขอจะไม่แสดงในหน้า SmartDocuments ที่สร้างขึ้น
   • แท็ก: อาร์เรย์ของแท็กที่เชื่อมโยงกับ API Smartdocs ใช้แท็กเพื่อจัดกลุ่ม API ที่คล้ายกันไว้ด้วยกัน เช่น คุณอาจใช้แท็ก "สถิติ" กับ API ทั้งหมดเกี่ยวกับสถิติ คุณจัดกลุ่ม API จากทรัพยากรต่างๆ ไว้ในแท็กเดียวได้ หาก API ทั้งหมดใช้แท็กเดียวกัน
7. เลือก Add Method ระบบจะเปลี่ยนเส้นทางคุณไปยังหน้าโมเดล ตอนนี้คุณแสดงผลและเผยแพร่เมธอดได้แล้ว

การแสดงผลโมเดล

หลังจากเพิ่ม API ลงในโมเดลแล้ว คุณจะแสดงผลโมเดลได้ การแสดงผลจะแปลงคำอธิบายของโมเดลของ API เป็นโหนด Drupal เมื่อการแสดงผลเสร็จสมบูรณ์ คุณจะมีโหนด Drupal 1 โหนดสำหรับ API แต่ละรายการ โดยที่โหนด Drupal แต่ละรายการจะสอดคล้องกับหน้า HTML

คุณเลือกแสดงผลทั้งโมเดลพร้อมกันหรือเลือก API แต่ละรายการเพื่อแสดงผลก็ได้

วิธีแสดงผลโมเดล

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก เนื้อหา >SmartDocs ในเมนูการดูแลระบบ Drupal
3. สำหรับโมเดลที่ต้องการแสดงผล ให้เลือกการแก้ไข API ในส่วนการดำเนินการ
4. เลือกการแก้ไขที่ต้องการแสดงผล คุณแสดงผลโหนดจากการแก้ไขโมเดลได้เพียงครั้งเดียวเท่านั้น
5. เลือกเมธอดในการแสดงผล
6. เลือกแสดงผลโหนดจากเมนูแบบเลื่อนลงตัวเลือก การอัปเดต
7. คลิกอัปเดต
8. หน้าจอการโหลดจะปรากฏขึ้นเพื่อดูความคืบหน้าในการแสดงผลโหนด
   หลังจากแสดงผลโหนดแล้ว รหัสของโหนด Drupal สำหรับ API แต่ละรายการจะปรากฏในคอลัมน์ การเชื่อมโยงโหนด ของโมเดล คลิกลิงก์ในคอลัมน์การเชื่อมโยงโหนดเพื่อดูโหนดที่แสดงผล

แทนที่จะเลือกแสดงผลโหนด คุณอาจเลือกแสดงผลและเผยแพร่โหนดเพื่อแสดงผลและเผยแพร่ API เป็นโหนด Drupal ได้ทันที

การเผยแพร่โหนด

ผู้ใช้พอร์ทัลจะไม่เห็นโหนดจนกว่าจะมีการเผยแพร่ คุณเลือกที่จะเผยแพร่โหนดระหว่างกระบวนการแสดงผลหรือไม่ก็ได้ หากเลือกที่จะไม่เผยแพร่โหนด คุณจะต้องเผยแพร่โหนดด้วยตนเองหลังจากการแสดงผลเสร็จสมบูรณ์

วิธีเผยแพร่โหนด

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก เนื้อหา >SmartDocument ในเมนูการดูแลระบบ Drupal
3. สำหรับโมเดลที่คุณต้องการเผยแพร่ ให้เลือกการแก้ไข API ในส่วนการดำเนินการ
4. เลือกการแก้ไขที่ต้องการเผยแพร่ คุณเผยแพร่โหนดจากการแก้ไขโมเดลได้เพียงครั้งเดียวเท่านั้น
5. เลือกวิธีที่จะเผยแพร่
6. เลือกโหนดในการแก้ไขที่จะเผยแพร่
7. เลือกเผยแพร่โหนดจากเมนูแบบเลื่อนลงตัวเลือก การอัปเดต
8. คลิกอัปเดต
9. ไปที่โหนดโดยเลือกรหัสโหนดในคอลัมน์ Node Association

โดยค่าเริ่มต้น URL ของ Drupal ไปยังโหนด API ที่เผยแพร่จะอยู่ในรูปแบบ http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath> ใช้ขั้นตอนต่อไปนี้เพื่อควบคุมรูปแบบของ URL

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือกการกำหนดค่า > การค้นหาและข้อมูลเมตา > ชื่อแทน URL > รูปแบบ ในเมนูการดูแลระบบ Drupal
3. ในส่วน Pattern สำหรับเส้นทางของ Method ทั้งหมด ให้ระบุวิธีสร้างเส้นทางที่คุณต้องการ
4. เลือกบันทึกการกำหนดค่า

เนื่องจากการแคชในพอร์ทัล คุณอาจไม่เห็นหน้าโมเดลปรากฏขึ้นทันทีหลังการเผยแพร่ หากจำเป็น คุณสามารถล้างแคช HTML ของ SmartDOCUMENT ด้วยตนเองโดยใช้กระบวนการต่อไปนี้

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก Configuration > SmartDocs ในเมนูการดูแลระบบ Drupal
3. คลิกสร้างแคชของโมเดล SmartDocuments ใหม่

การยกเลิกการเผยแพร่โหนด

คุณยกเลิกการเผยแพร่โหนดที่เผยแพร่ได้ทุกเมื่อ การยกเลิกการเผยแพร่โหนดจะทำให้ผู้ใช้พอร์ทัลมองไม่เห็นโหนดดังกล่าว

วิธียกเลิกการเผยแพร่โหนด

1. เข้าสู่ระบบพอร์ทัลในฐานะผู้ใช้ที่มีสิทธิ์ผู้ดูแลระบบหรือสิทธิ์ในการสร้างเนื้อหา
2. เลือก เนื้อหา > SmartDocs ในเมนูการดูแลระบบ Drupal
3. สำหรับโมเดลที่คุณต้องการยกเลิกการเผยแพร่ ให้เลือกการแก้ไข API ในส่วนการดำเนินการ
4. เลือกการแก้ไขโมเดลของโหนดที่คุณต้องการยกเลิกการเผยแพร่
5. เลือกโหนดในการแก้ไขเพื่อยกเลิกการเผยแพร่
6. เลือกยกเลิกการเผยแพร่โหนดจากเมนูแบบเลื่อนลงตัวเลือก การอัปเดต
7. คลิกอัปเดต

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>