Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.
Tóm tắt dự án
- Tổ chức nguồn mở:
- Tổ chức OWASP
- Người viết nội dung kỹ thuật:
- sshniro
- Tên dự án:
- Cải tiến Tài liệu về ZAP API
- Thời lượng dự án:
- Thời gian 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 tôi 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 một cách hiệu quả, bạn cần hiểu rõ về giao diện người dùng. Điều này là do hầu hết các API tương quan trực tiếp với giao diện người dùng của proxy ZA. API được ghi nhận đầy đủ và tài liệu về trường hợp sử dụng/ trường hợp sử dụng có thể hỗ trợ việc vượt qua nút thắt cổ chai này khi dùng thử 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ố có liên quan và mang lại ít cơ hội hơn để cộng đồng đóng góp vào tài liệu API. Ngoài ra, giao diện người dùng trên nền tảng web (phiên bản dành cho 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ần biết 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.
Mục đích là tạo lại tài liệu API theo Quy cách mở 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 để xây dựng, duy trì và kiểm thử API. Bạn có thể dùng thông số kỹ thuật Open API hoàn chỉnh của ZAP để tự động tạo các 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 một ứng dụng kiểm thử API phong phú cho người dùng.
Ngoài tài liệu về API, tôi dự định sử dụng trình chuyển đổi swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) để tạo các tài liệu về API theo định dạng Markdown. Phương pháp này (swagger-converter) giúp đơn giản hoá việc tạo tài liệu về API RESTful mới nhất bằng cách kết hợp tài liệu được viết thủ công với tài liệu về API do Swagger tạo tự động. Kết quả sẽ tương tự như tài liệu về 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 các API để thực hiện một nhiệm vụ nhất định. Ví dụ: Quét API Trình thu thập thông tin là một tác vụ kéo dài và người dùng cần liên tục thăm dò 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ề API nào được sử 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 hơn 380 API đã được triển khai trong proxy ZA. Ban đầu, tôi dự định ghi lại tất cả API, kèm theo nội dung mô tả về API, thông tin về các tham số, phản hồi thành công và không thành công của các API này. Hiện đã có đầu mối liên hệ mẫu. Bạn có thể xem thêm thông tin chi tiết trong đề xuất đã liên kết.
Giai đoạn 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 Open API cho Active Quét, Core API (150+). Song song với việc tạo tệp swagger, tài liệu 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 tác vụ cụ thể cũng sẽ được tạo. Tệp này có thể được tạo phiên bản và tự động tạo để loại bỏ tác vụ thủ công và các tệp đánh dấu kết quả có thể được lưu trữ 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 trình thu thập dữ liệu, tự động cập nhật, ngữ cảnh, trạng thái, tìm kiếm API và tạo bài viết trường hợp sử dụng liên quan thông qua tệp Markdown.
Giai đoạn cuối cùng sẽ đề cập đến những API không được ghi nhận trong tài liệu và các trường hợp sử dụng liên quan. Trong tháng trước, tôi cũng đã lên kế hoạch đề 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ụ.