이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- OWASP 재단
- 테크니컬 라이터:
- 시니로
- 프로젝트 이름:
- ZAP API 문서 개선
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
ZAP는 데스크톱 인터페이스를 통해 가능한 거의 모든 작업을 수행할 수 있게 해주는 매우 강력한 API를 보유하고 있습니다. 하지만 API를 효과적으로 사용하려면 UI를 잘 이해하고 있어야 합니다. 이는 대부분의 API가 ZA 프록시의 사용자 인터페이스와 직접적인 상관관계가 있기 때문입니다. 잘 문서화된 API와 사용 사례/ 사용 사례 문서는 API를 사용해 볼 때 이러한 병목 현상을 극복하는 데 도움이 될 수 있습니다.
현재 API 문서는 자동으로 생성되며 관련 매개변수에 대한 정보를 거의 제공하지 않으며 커뮤니티에서 API 문서에 기여할 기회가 적습니다. 또한 ZAP 내에서 사용되는 웹 기반 UI (데스크톱 버전)도 호출을 위해 자동 생성된 API 목록을 사용합니다. 이 웹 기반 API 호출 UI는 API 사용 방법 및 API 호출 시 예상되는 사항 ( 예: API 결과)에 대한 매우 제한된 정보도 제공합니다. 따라서 이 제안에서는 API를 문서화하는 새로운 접근 방식을 제안합니다.
이 아이디어는 Open API 3 사양을 사용하여 API 문서를 다시 만드는 것입니다. Open API는 개발자, 테스터, 개발 운영팀이 API를 빌드, 유지관리, 테스트할 수 있는 공통 프레임워크를 제공합니다. ZAP에 대한 완성된 Open API 사양을 사용하여 스웨거 파일을 자동으로 생성할 수 있습니다. Swagger 파일을 ZAP의 웹 애플리케이션 (데스크톱 앱) UI에 통합하여 사용자에게 풍부한 API 테스트 클라이언트를 제공할 수 있습니다.
API 문서 외에도 swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) 변환기를 사용하여 마크다운 형식으로 API 문서를 생성할 계획입니다. 이 접근 방식 (스웨거 변환기)은 Swagger에서 생성된 자동 생성된 API 문서와 직접 작성한 문서를 결합하여 최신 RESTful API 문서의 생성을 간소화합니다. 결과는 GitHub의 API 문서와 유사합니다. (https://developer.github.com/v3/). 직접 작성한 문서에는 특정 작업을 수행하기 위해 API를 사용하는 방법을 개략적으로 설명하는 문서가 포함되어 있습니다. 예를 들어 Spider API 스캔은 장기 실행 작업이므로 사용자는 API를 지속적으로 폴링하여 API 상태를 확인해야 합니다. 따라서 이러한 고급 문서에서는 작업을 수행하는 데 어떤 API를 사용해야 하는지 설명하고, 추가로 읽어볼 수 있도록 자동 생성된 스웨거 문서를 안내합니다.
ZA 프록시에서 총 380개 이상의 API가 구현되었습니다. 처음에는 모든 API를 API에 대한 설명, 매개변수 관련 정보, API의 성공 및 실패 응답과 함께 문서화하는 것을 제안합니다. 이미 샘플 POC가 완료되었으며 추가 세부정보는 연결된 제안서에서 확인할 수 있습니다.
3개월은 3단계로 구분됩니다. 첫 번째 단계에서는 Active Scan, Core API (150+)에 대한 Open API 사양을 만듭니다. 스웨거 파일 생성과 동시에 API를 사용하여 특정 작업을 수행하는 방법에 대한 관련 사용 사례 문서/ 개략적 문서도 생성됩니다. 버전을 관리하고 자동 생성하여 수작업을 없애고 마크다운 파일을 웹페이지로 호스팅하거나 PDF로 내보낼 수 있습니다.
두 번째 단계에서는 Spider, Autoupdate, Context, Status, Search API를 문서화하고 마크다운 파일을 통해 관련 사용 사례 문서를 작성하는 방법을 다룹니다.
마지막 단계에서는 문서화되지 않은 나머지 API와 관련 사용 사례를 다룹니다. 지난달에는 작업을 수행하기 위해 여러 API 구성요소를 호출해야 하는 사용 사례도 다룰 계획입니다.