Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
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 niezwykle zaawansowany interfejs API, który pozwala nam wykonywać prawie wszystkie te czynności, które są dostępne w interfejsie komputerowym. Jednak do efektywnego korzystania z interfejsów API potrzeba dobrej znajomości ich interfejsu. Dzieje się tak, ponieważ większość interfejsów API jest bezpośrednio powiązana z interfejsem serwera proxy ZA. Dobrze udokumentowany interfejs API i dokument dotyczący użytkowania/ przypadku użycia mogą pomóc w przezwyciężeniu tego wąskiego gardła podczas testowania interfejsów API.
Obecnie dokumenty dotyczące interfejsu API są generowane automatycznie, zawierają niewiele informacji o parametrach i zmniejszają szanse społeczności na udział w pracy nad dokumentacją API. Dodatkowo interfejs internetowy (wersja komputerowa) używany w ZAP używa też automatycznie wygenerowanej listy interfejsów API do wywoływania. Ten internetowy interfejs wywołań interfejsów API zawiera też bardzo ograniczone informacje o tym, jak używać interfejsu API i czego można się spodziewać podczas wywoływania interfejsów API ( np. wyniki interfejsu API). Dlatego też proponuję nowe podejście do dokumentowania interfejsów API.
Celem jest ponowne utworzenie dokumentów interfejsu API za pomocą specyfikacji Open API 3. Open API udostępnia wspólną platformę dla deweloperów, testerów i programistów do tworzenia, utrzymywania i testowania interfejsów API. Pełne specyfikacje Open API dla ZAP mogą zostać użyte do automatycznego generowania plików z elementami „Swagger”. Pliki Swagger można zintegrować z interfejsem aplikacji internetowej ZAP (aplikacja komputerowa), aby zapewnić użytkownikom rozbudowany klient do testowania interfejsów API.
Oprócz dokumentacji API zamierzam użyć konwertera swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup), aby wygenerować dokumentację API w formacie Markdown. To podejście (swagger-converter) upraszcza generowanie aktualnej dokumentacji API REST, ponieważ łączy dokumentację napisaną odręcznie z automatycznie generowaną dokumentacją API opracowaną przez Swagger. Wyniki będą podobne do dokumentacji interfejsu API GitHuba. (https://developer.github.com/v3/). Ten odręczny dokument będzie zawierać ogólne dokumenty wyjaśniające, jak należy używać interfejsów API do wykonywania określonego zadania. Na przykład skanowanie interfejsu Spider API jest zadaniem długo trwającym, a użytkownik powinien stale przeprowadzać ankiety dotyczące interfejsu API, aby poznać jego stan. W związku z tym dokumenty te będą omawiać, które interfejsy API można wykorzystać do wykonania określonych czynności, i wskazać automatycznie wygenerowane dokumenty, które zawierają przydatne informacje.
Łącznie wdrożono ponad 380 interfejsów API na serwerze proxy w ZA. Początkowo chcę udokumentować wszystkie interfejsy API wraz z ich opisem, informacjami o ich parametrach oraz reakcjach zakończonych niepowodzeniem. Wzięliśmy już pod uwagę przykładową koncepcję koncepcyjną. Dodatkowe szczegóły znajdziesz w powiązanej ofercie pakietowej.
Ten trzymiesięczny okres zostanie podzielony na trzy etapy. W pierwszym etapie utworzymy specyfikacje Open API dla Active Scan oraz Core API (w wersji 150). Równolegle z tworzeniem plików „odrobiny” utworzymy też odpowiednią dokumentację przypadku użycia lub ogólne dokumenty na temat korzystania z interfejsów API do wykonywania określonych zadań. Te dane mogą być przetwarzane w wersji i automatycznie generowane, aby nie uwzględniać pracy ręcznej, a powstałe pliki Markdown mogą być hostowane jako strony internetowe lub eksportowane w formacie PDF.
W drugim etapie zaprezentujemy informacje o pająku, automatycznej aktualizacji, kontekstach, stanach i interfejsach Search API oraz na tworzeniu odpowiednich artykułów z przykładami użycia za pomocą plików Markdown.
Ostatni etap obejmie resztę nieudokumentowanych interfejsów API i ich odpowiednie przypadki użycia. W zeszłym miesiącu zamierzam też uwzględnić przypadki użycia, które wymagają wywoływania wielu komponentów interfejsu API w celu wykonania zadania.