На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Фонд OWASP
- Технический писатель:
- сшниро
- Название проекта:
- Улучшение документации ZAP API
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
ZAP имеет чрезвычайно мощный API, который позволяет нам делать практически все, что возможно, через интерфейс рабочего стола. Однако для эффективного использования API необходимо хорошее понимание пользовательского интерфейса. Это связано с тем, что большинство API-интерфейсов напрямую связаны с пользовательским интерфейсом прокси-сервера ZA. Хорошо документированный API и документ по использованию/варианту использования могут помочь преодолеть это узкое место при опробовании API.
В настоящее время документы API генерируются автоматически, предоставляют мало информации о задействованных параметрах и дают меньше возможностей сообществу внести свой вклад в документацию API. Кроме того, веб-интерфейс (версия для ПК), используемый внутри ZAP, также использует для вызова автоматически созданный список API. Этот веб-интерфейс вызова API также предоставляет очень ограниченную информацию о том, как использовать API и чего ожидать при вызове API (например, результаты API). Поэтому в этом предложении я предлагаю новый подход к документированию API.
Идея состоит в том, чтобы воссоздать документы API с использованием спецификаций Open API 3. Открытый API предоставляет разработчикам, тестировщикам и специалистам по разработке общую структуру для создания, обслуживания и тестирования API. Заполненные спецификации Open API для ZAP можно использовать для автоматического создания файлов swagger. Файлы Swagger можно интегрировать в пользовательский интерфейс веб-приложения ZAP (приложение для ПК), чтобы предоставить пользователям богатый клиент для тестирования API.
Помимо документации по API, я планирую использовать конвертер swaggerToMarkdown ( https://github.com/Swagger2Markup/swagger2markup ) для создания документации API в формате Markdown. Этот подход (swagger-converter) упрощает создание актуальной документации по API RESTful за счет объединения документации, написанной вручную, с автоматически созданной документацией по API, созданной Swagger. Результаты будут аналогичны документации API Github. ( https://developer.github.com/v3/ ). Этот рукописный документ будет содержать документы высокого уровня, объясняющие, как следует использовать API для выполнения определенной задачи. Например, сканирование API Spider — это длительная задача, и пользователь должен постоянно опрашивать API, чтобы узнать состояние API. Следовательно, в этих документах высокого уровня будет обсуждаться, какие API-интерфейсы будут использоваться для выполнения действия, и указываться на автоматически сгенерированные документы Swagger для дальнейшего чтения.
Всего в ZA proxy реализовано более 380 API. Первоначально я предлагаю документировать все API с описанием API, информацией о параметрах, успехах и ошибках API. Образец POC уже составлен, а дополнительную информацию можно увидеть в связанном предложении.
Трехмесячный период будет разделен на три этапа. На первом этапе будут созданы спецификации Open API для Active Scan, Core API (более 150). Параллельно с созданием файлов swagger также будет создана соответствующая документация по вариантам использования/документы высокого уровня о том, как использовать API для выполнения конкретных задач. Для этого можно создать версии и автоматически сгенерировать их, чтобы исключить ручную работу, а полученные файлы уценки можно разместить в виде веб-страниц или экспортировать в формате PDF.
Второй этап будет охватывать документирование API Spider, Autoupdate, Context, Status, Search и создание соответствующих статей о вариантах использования с помощью файлов Markdown.
На заключительном этапе будут рассмотрены остальные недокументированные API и соответствующие варианты их использования. В прошлом месяце я планирую также охватить случаи использования, требующие вызова нескольких компонентов API для выполнения задачи.