Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source
- Fundacja OWASP
- Pisarz techniczny:
- sshniro
- Nazwa projektu:
- Ulepszenie dokumentacji interfejsu ZAP API
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
ZAP ma bardzo wydajny interfejs API, który pozwala nam robić prawie wszystko, co możliwe w interfejsie komputerowym. Aby jednak skutecznie korzystać z interfejsów API, trzeba dobrze poznać interfejs użytkownika. Dzieje się tak, ponieważ większość interfejsów API jest bezpośrednio skorelowana z interfejsem serwera proxy ZA. Dobrze udokumentowany interfejs API oraz dokument z informacjami o użyciu i przypadkach użycia mogą pomóc w pozbyciu się tego wąskiego gardła podczas testowania interfejsów API.
Obecnie dokumenty interfejsu API są generowane automatycznie, zawierają niewiele informacji o zaangażowanych parametrach i dają mniejsze możliwości społeczności do współtworzenia dokumentacji interfejsu API. Dodatkowo interfejs użytkownika oparty na przeglądarce (wersja na komputer) używany w ZAP również korzysta z automatycznie generowanej listy interfejsu API. To internetowe UI wywoływania interfejsu API zawiera też bardzo ograniczone informacje o tym, jak korzystać z interfejsu API i czego można się spodziewać podczas jego wywoływania ( np. wyniki interfejsu API). Dlatego w tej propozycji sugeruję nowe podejście do dokumentowania interfejsów API.
Chodzi o odtworzenie dokumentów API według specyfikacji Open API 3. Interfejs Open API zapewnia wspólny framework dla programistów, testerów i zespołów Dev-Ops do tworzenia, utrzymywania i testowania interfejsów API. Wypełnione specyfikacje OpenAPI dla ZAP można wykorzystać do automatycznego generowania plików swagger. Pliki Swaggera można zintegrować z interfejsem aplikacji internetowej ZAP (aplikacji komputerowej), aby zapewnić użytkownikom bogatego klienta do testowania interfejsu API.
Oprócz dokumentacji interfejsu API planuję użyć konwertera swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) do generowania dokumentów interfejsu API w formacie Markdown. To podejście (konwerter Swagger) upraszcza generowanie aktualnej dokumentacji interfejsu RESTful API poprzez połączenie dokumentacji napisanej ręcznie z automatycznie wygenerowaną dokumentacją interfejsu API wygenerowaną przez Swagger. Wyniki będą podobne do dokumentacji interfejsu API Github. (https://developer.github.com/v3/). Ten dokument z odręcznym tekstem będzie zawierać ogólne dokumenty wyjaśniające, jak używać interfejsów API do wykonywania określonych zadań. Na przykład skanowanie interfejsu Spider API to długotrwałe zadanie, dlatego użytkownik powinien stale sprawdzać stan interfejsu API. Dlatego te dokumenty ogólne opisują, których interfejsów API należy używać do wykonywania czynności, i wskazują automatycznie generowane dokumenty swagger, które należy przeczytać.
W ZA proxy zaimplementowano ponad 380 interfejsów API. Proponuję na początek udokumentowanie wszystkich interfejsów API, podając ich opis, informacje o parametrach oraz odpowiedzi na powodzenie i błędy. Przykładowa inicjatywa została już przeprowadzona, a więcej informacji znajdziesz w załączonej ofercie.
Ten 3-miesięczny okres będzie podzielony na 3 fazy. W pierwszej fazie zostaną utworzone specyfikacje interfejsów Open API dla Active Scan i interfejsów podstawowych (ponad 150 interfejsów). Równolegle z tworzeniem plików swagger zostaną też utworzone odpowiednie dokumenty dotyczące przypadków użycia lub ogólne dokumenty dotyczące sposobu korzystania z interfejsów API do wykonywania określonych zadań. Można je wersjonować i automatycznie generować, aby uniknąć ręcznej pracy. Wyniki w formacie markdown można hostować jako strony internetowe lub eksportować jako pliki PDF.
Druga faza obejmie udokumentowanie interfejsów API pająka, automatycznej aktualizacji, kontekstu, stanu i wyszukiwarki oraz utworzenie odpowiednich artykułów o przypadkach użycia za pomocą plików Markdown.
Ostatni etap obejmie pozostałe nieudokumentowane interfejsy API i odpowiednie przypadki użycia. W ostatnim miesiącu omówię też przypadki użycia, które wymagają wywołania wielu komponentów interfejsu API do wykonania zadania.