이 페이지에는 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 파일을 자동으로 생성할 수 있습니다. Swagger 파일을 ZAP의 웹 애플리케이션 (데스크톱 앱) UI에 통합하여 사용자에게 풍부한 API 테스트 클라이언트를 제공할 수 있습니다.
API 문서 외에도 swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) 변환기를 사용하여 API 문서를 마크다운 형식으로 생성할 계획입니다. 이러한 접근 방식 (swagger-Converter)은 직접 작성한 문서와 Swagger에서 생성된 자동 생성된 API 문서를 결합하여 최신 RESTful API 문서의 생성을 간소화합니다. 결과는 GitHub의 API 문서와 유사합니다. (https://developer.github.com/v3/). 이 직접 작성한 문서에는 특정 작업을 수행하기 위해 API를 사용하는 방법을 설명하는 개략적인 문서가 포함되어 있습니다. 예를 들어 Spider API 스캔은 장기 실행 작업이며 사용자는 API의 상태를 파악하기 위해 API를 지속적으로 폴링해야 합니다. 따라서 이러한 개략적인 문서에서는 작업을 실행하는 데 사용할 API를 설명하고 추가 읽기를 위해 자동 생성된 스웨거 문서를 가리킵니다.
총 380개 이상의 API가 ZA 프록시에 구현되었습니다. 처음에는 모든 API를 API에 대한 설명, 매개변수에 관한 정보, API의 성공 및 실패 응답과 함께 문서화하는 것을 제안합니다. 샘플 POC가 이미 완료되었으며 추가 세부정보는 연결된 제안서에서 확인할 수 있습니다.
3개월의 기간은 3단계로 구분됩니다. 첫 번째 단계에서는 Active Scan, Core API (150+)용 Open API 사양을 만듭니다. 스웨거 파일 생성과 동시에 API를 사용하여 특정 작업을 수행하는 방법에 대한 관련 사용 사례 문서/ 개략적인 문서도 작성됩니다. 버전이 관리되고 자동 생성되어 수작업이 필요 없고 마크다운 파일이 웹페이지로 호스팅되거나 PDF로 내보내질 수 있습니다.
두 번째 단계에서는 Spider, Autoupdate, Context, Status, Search API를 문서화하고 마크다운 파일을 통해 관련 사용 사례 문서를 작성하는 방법을 다룹니다.
마지막 단계에서는 문서화되지 않은 나머지 API와 관련 사용 사례를 살펴봅니다. 지난달에는 작업을 수행하기 위해 여러 API 구성요소를 호출해야 하는 사용 사례도 다룰 계획입니다.