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