หน้านี้มีรายละเอียดของโครงการการเขียนเชิงเทคนิคที่ยอมรับสำหรับ Google Season of Docs
ข้อมูลสรุปของโปรเจ็กต์
- องค์กรโอเพนซอร์ส:
- มูลนิธิ OWASP
- ผู้เขียนด้านเทคนิค:
- sshniro
- ชื่อโปรเจ็กต์:
- การเพิ่มประสิทธิภาพเอกสารประกอบ ZAP API
- ระยะเวลาของโปรเจ็กต์:
- ระยะเวลามาตรฐาน (3 เดือน)
คำอธิบายโปรเจ็กต์
ZAP มี API ที่ทรงพลังอย่างมากซึ่งเปิดโอกาสให้เราทำผ่านอินเทอร์เฟซบนเดสก์ท็อปได้เกือบทุกอย่าง อย่างไรก็ตาม หากต้องการใช้ API อย่างมีประสิทธิภาพ คุณจำเป็นต้องมีความเข้าใจเกี่ยวกับ UI เป็นอย่างดี เนื่องจาก API ส่วนใหญ่เกี่ยวข้องโดยตรงกับอินเทอร์เฟซผู้ใช้ของพร็อกซี ZA API และเอกสารการใช้งาน/ กรณีการใช้งานที่มีเอกสารประกอบเป็นอย่างดีจะช่วยแก้ปัญหาจุดคอขวดนี้เมื่อลองใช้ API
ปัจจุบันเอกสาร API ได้รับการสร้างขึ้นโดยอัตโนมัติ ให้ข้อมูลเพียงเล็กน้อยเกี่ยวกับพารามิเตอร์ที่เกี่ยวข้อง และทำให้ชุมชนมีโอกาสน้อยลงที่จะร่วมให้ข้อมูลในเอกสารประกอบของ API นอกจากนี้ UI บนเว็บ (เวอร์ชันเดสก์ท็อป) ที่ใช้ภายใน ZAP ยังใช้รายการ API ที่สร้างขึ้นโดยอัตโนมัติสำหรับการเรียกใช้ด้วย UI สำหรับเรียกใช้ API แบบเว็บนี้ให้ข้อมูลอย่างจำกัดมากเกี่ยวกับวิธีใช้ API และสิ่งที่จะเกิดขึ้นเมื่อเรียกใช้ API ( เช่น ผลลัพธ์ API) ดังนั้น ในข้อเสนอนี้ ฉันจึงแนะนำวิธีใหม่ในการบันทึก API
แนวคิดคือการสร้างเอกสาร API ใหม่ด้วยข้อกำหนดของ Open API 3 Open API มีเฟรมเวิร์กทั่วไปสำหรับนักพัฒนาซอฟต์แวร์ ผู้ทดสอบ และนักพัฒนาในการสร้าง บำรุงรักษา และทดสอบ API คุณสามารถใช้ข้อกำหนดของ Open API ที่สมบูรณ์ของ ZAP เพื่อสร้างไฟล์ Sswคนหนึ่ง โดยอัตโนมัติ ไฟล์ Swagger สามารถผสานรวมเข้ากับ UI ของเว็บแอปพลิเคชัน (แอปเดสก์ท็อป) ของ ZAP เพื่อมอบไคลเอ็นต์การทดสอบ API ที่สมบูรณ์ให้กับผู้ใช้
นอกเหนือจากเอกสารประกอบของ API เรายังวางแผนจะใช้ตัวแปลง swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) ในการสร้างเอกสาร API ในรูปแบบ Markdown วิธีการนี้ (ตัวแปลงรหัส) นี้ทำให้การสร้างเอกสารประกอบของ RESTful API ที่อัปเดตง่ายขึ้นโดยการรวบรวมเอกสารประกอบที่เขียนด้วยมือเข้ากับเอกสารประกอบของ API ที่สร้างขึ้นโดยอัตโนมัติซึ่งสร้างโดย Swคนหนึ่ง โดยผลลัพธ์จะคล้ายกับเอกสารประกอบเกี่ยวกับ API ของ GitHub (https://developer.github.com/v3/). เอกสารที่เขียนด้วยลายมือนี้จะมีเอกสารระดับสูงที่อธิบายว่าควรใช้ API เพื่อทำงานบางอย่างอย่างไร เช่น การสแกน Spider API เป็นงานที่ใช้เวลานาน และผู้ใช้ควรสำรวจ API อย่างต่อเนื่องเพื่อให้ทราบสถานะของ API ดังนั้นเอกสารระดับสูงเหล่านี้จะกล่าวถึง API ที่จะใช้ในการดำเนินการ และชี้ไปที่เอกสารสรุปที่สร้างขึ้นโดยอัตโนมัติเพื่ออ่านต่อ
มีการติดตั้ง API ทั้งหมดในพร็อกซี ZA จำนวน 380+ รายการ ในช่วงแรกฉันเสนอที่จะจัดทำเอกสารเกี่ยวกับ API ทั้งหมดพร้อมคำอธิบายสำหรับ API, ข้อมูลเกี่ยวกับพารามิเตอร์, การตอบสนองที่สำเร็จ และความล้มเหลวของ API เราได้ทำ POC ตัวอย่างเรียบร้อยแล้ว และสามารถดูรายละเอียดเพิ่มเติมได้ในข้อเสนอที่ลิงก์
ระยะเวลา 3 เดือนจะแบ่งออกเป็น 3 ช่วง ระยะแรกจะสร้างข้อกำหนดของ Open API สำหรับ Active Scan, Core API (150+) โดยจะสร้างเอกสารประกอบเกี่ยวกับกรณีการใช้งานที่เกี่ยวข้อง/ เอกสารระดับสูงเกี่ยวกับวิธีใช้ API เพื่อทำงานบางอย่างไปด้วย โดยอาจกำหนดเวอร์ชันและสร้างโดยอัตโนมัติเพื่อนำงานที่ต้องทำด้วยตนเองออก และไฟล์มาร์กดาวน์ที่สร้างขึ้นสามารถโฮสต์เป็นหน้าเว็บหรือส่งออกเป็น PDF ได้
ขั้นตอนที่ 2 จะครอบคลุมเนื้อหาเกี่ยวกับสไปเดอร์, การอัปเดตอัตโนมัติ, บริบท, สถานะ, Search API และการสร้างบทความเกี่ยวกับกรณีการใช้งานที่เกี่ยวข้องผ่านไฟล์มาร์กดาวน์
ระยะสุดท้ายจะครอบคลุม API ที่เหลือที่ไม่ได้มีการระบุไว้และกรณีการใช้งานที่เกี่ยวข้อง ในเดือนที่ผ่านมา ฉันวางแผนจะพูดถึง Use Case ที่ต้องมีการเรียกใช้คอมโพเนนต์ API หลายรายการในการทำงานด้วย