Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- OWASP Foundation
- Tác giả kỹ thuật:
- sshniro
- Tên dự án:
- Cải thiện tài liệu về ZAP API
- Độ dài dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
ZAP có một API cực kỳ mạnh mẽ cho phép chúng ta làm gần như mọi việc có thể thông qua giao diện máy tính. Tuy nhiên, để sử dụng các API này một cách hiệu quả, bạn cần hiểu rõ giao diện người dùng. Điều này là do hầu hết các API đều liên quan trực tiếp đến giao diện người dùng của proxy ZA. Tài liệu về API và cách sử dụng/ trường hợp sử dụng được ghi chép cẩn thận có thể giúp bạn vượt qua nút thắt cổ chai này khi dùng thử các API.
Hiện tại, tài liệu API được tạo tự động, cung cấp ít thông tin về các tham số liên quan và ít tạo cơ hội cho cộng đồng đóng góp vào tài liệu API. Ngoài ra, giao diện người dùng dựa trên web (phiên bản máy tính) dùng trong ZAP cũng sử dụng danh sách API được tạo tự động để gọi. Giao diện người dùng gọi API dựa trên nền tảng web này cũng cung cấp thông tin rất hạn chế về cách sử dụng API và những điều có thể xảy ra khi gọi API ( ví dụ: kết quả API). Do đó, trong đề xuất này, tôi đề xuất một phương pháp mới để ghi lại API.
Ý tưởng là tạo lại tài liệu API bằng Thông số kỹ thuật Open API 3. Open API cung cấp một khung chung cho nhà phát triển, người kiểm thử và nhà phát triển vận hành để xây dựng, duy trì và kiểm thử API. Bạn có thể sử dụng thông số kỹ thuật API mở hoàn chỉnh cho ZAP để tự động tạo tệp swagger. Bạn có thể tích hợp các tệp Swagger vào giao diện người dùng của ứng dụng web (Ứng dụng máy tính) của ZAP để cung cấp cho người dùng một ứng dụng kiểm thử API phong phú.
Ngoài tài liệu API, tôi dự định sử dụng trình chuyển đổi swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) để tạo tài liệu API ở định dạng Markdown. Phương pháp này (swagger-converter) đơn giản hoá việc tạo tài liệu API RESTful mới nhất bằng cách kết hợp tài liệu được viết tay với tài liệu API được tạo tự động do Swagger tạo. Kết quả sẽ tương tự như tài liệu API của GitHub. (https://developer.github.com/v3/). Tài liệu viết tay này sẽ có các tài liệu cấp cao giải thích cách sử dụng API để thực hiện một nhiệm vụ nhất định. Ví dụ: quét API Spider là một tác vụ chạy trong thời gian dài và người dùng phải liên tục thăm dò ý kiến API để biết trạng thái của API. Do đó, các tài liệu cấp cao này sẽ thảo luận về những API nào sẽ được dùng để thực hiện một hành động và trỏ đến các tài liệu swagger được tạo tự động để đọc thêm.
Tổng cộng có hơn 380 API đã được triển khai trong proxy ZA. Ban đầu, tôi đề xuất ghi lại tất cả các API cùng với mô tả về API, thông tin về tham số, phản hồi thành công và không thành công của API. Chúng tôi đã thực hiện một POC mẫu và bạn có thể xem thêm thông tin chi tiết trong đề xuất được liên kết.
Khoảng thời gian 3 tháng này sẽ được chia thành 3 giai đoạn. Giai đoạn đầu tiên sẽ tạo thông số kỹ thuật API mở cho tính năng Quét chủ động, API cốt lõi (trên 150). Song song với việc tạo tệp swagger, tài liệu về trường hợp sử dụng liên quan/ tài liệu cấp cao về cách sử dụng API để thực hiện các nhiệm vụ cụ thể cũng sẽ được tạo. Bạn có thể tạo phiên bản và tạo tự động để loại bỏ công việc thủ công, đồng thời lưu trữ các tệp markdown đã tạo dưới dạng trang web hoặc xuất dưới dạng PDF.
Giai đoạn thứ hai sẽ bao gồm việc ghi lại Spider, Tự động cập nhật, Ngữ cảnh, Trạng thái, API Tìm kiếm và tạo các bài viết về trường hợp sử dụng có liên quan thông qua tệp Markdown.
Giai đoạn cuối cùng sẽ đề cập đến các API chưa được ghi nhận còn lại và các trường hợp sử dụng có liên quan. Trong tháng cuối cùng, tôi cũng dự định sẽ đề cập đến các trường hợp sử dụng yêu cầu gọi nhiều thành phần API để thực hiện một tác vụ.