이 페이지에는 Google 시즌의 Docs에 승인된 기술 글쓰기 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- OWASP Foundation
- 기술 문서 작성자:
- sshniro
- 프로젝트 이름:
- 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 파일을 자동 생성할 수 있습니다. Swagger 파일을 ZAP의 웹 애플리케이션 (데스크톱 앱) UI에 통합하여 사용자에게 풍부한 API 테스트 클라이언트를 제공할 수 있습니다.
API 문서와 별도로 swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) 변환기를 사용하여 마크다운 형식으로 API 문서를 생성할 계획입니다. 이 접근 방식 (swagger 변환기)은 직접 작성한 문서와 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개월 기간은 세 단계로 나뉩니다. 첫 번째 단계에서는 능동 스캔, 핵심 API (150개 이상)의 Open API 사양을 만듭니다. 스와거 파일을 만드는 것과 동시에 API를 사용하여 특정 작업을 실행하는 방법에 관한 관련 사용 사례 문서/ 대략적인 문서도 생성됩니다. 버전 관리 및 자동 생성하여 수동 작업을 없앨 수 있으며 결과 Markdown 파일을 웹페이지로 호스팅하거나 PDF로 내보낼 수 있습니다.
두 번째 단계에서는 Spider, 자동 업데이트, 컨텍스트, 상태, 검색 API를 문서화하고 마크다운 파일을 통해 관련 사용 사례 문서를 작성하는 방법을 다룹니다.
마지막 단계에서는 문서화되지 않은 나머지 API와 관련 사용 사례를 다룹니다. 다음 달에는 작업을 실행하기 위해 여러 API 구성요소를 호출해야 하는 사용 사례도 다룰 예정입니다.