Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- Base OWASP
- Redator técnico:
- sshniro (em inglês)
- Nome do projeto:
- Melhoria da documentação da API ZAP
- Duração do projeto:
- Duração padrão (3 meses)
Project description
O ZAP tem uma API extremamente poderosa que nos permite fazer quase tudo o que é possível pela interface do desktop. No entanto, para usar as APIs de forma eficaz, é necessário ter um bom entendimento da IU. Isso ocorre porque a maioria das APIs está diretamente correlacionada à interface de usuário do proxy de ZA. Uma API bem documentada e um documento de uso/ caso de uso podem ajudar a superar esse gargalo ao testar as APIs.
Atualmente, os documentos da API são gerados automaticamente, fornecem pouca informação sobre os parâmetros envolvidos e oferecem menos oportunidades para a comunidade contribuir com a documentação da API. Além disso, a interface baseada na Web (versão desktop) usada no ZAP também usa a lista de APIs gerada automaticamente para invocação. Esta interface de invocação de API baseada na web também fornece informações muito limitadas sobre como usar a API e o que esperar ao invocar as APIs ( por exemplo, resultados da API). Por isso, nesta proposta, estou sugerindo uma nova abordagem para documentar as APIs.
A ideia é recriar os documentos da API com as especificações Open API 3. A Open API fornece um framework comum para desenvolvedores, testadores e desenvolvedores criarem, manterem e testarem APIs. As especificações de Open API completas para ZAP podem ser usadas para gerar automaticamente os arquivos de distribuição. Os arquivos Swagger podem ser integrados à interface do aplicativo da Web (aplicativo de desktop) do ZAP para fornecer um cliente de teste de API avançado para os usuários.
Além da documentação da API, estou planejando usar o conversor swaggerToMarkdown (https://github.com/Swagger2Markup/swagger2markup) para gerar os documentos da API no formato Markdown. Essa abordagem (swagger-converter) simplifica a geração de documentação da API RESTful atualizada, combinando a documentação feita à mão com a documentação da API gerada automaticamente e produzida pelo Swagger. Os resultados serão semelhantes à documentação da API do GitHub. (https://developer.github.com/v3/). Este documento manuscrito terá documentos de alto nível explicando como as APIs devem ser usadas para executar uma determinada tarefa. Por exemplo, uma verificação da API Spider é uma tarefa de longa duração e o usuário deve pesquisar continuamente a API para saber o status da API. Por isso, esses documentos de alto nível vão discutir quais APIs devem ser usadas para executar uma ação e indicar os documentos de brindes gerados automaticamente para leitura adicional.
Um número total de mais de 380 APIs foram implementadas no proxy de ZA. Inicialmente, proponho a documentação de todas as APIs com uma descrição delas, informações sobre os parâmetros e as respostas de êxito e falha. Já foi feito um exemplo de POC, e mais detalhes podem ser vistos na proposta vinculada.
O período de três meses será dividido em três fases. A primeira fase vai criar as especificações da Open API para o Active Scan, as APIs Core (mais de 150). Além da criação dos arquivos swagger, também serão criados a documentação de caso de uso relevante e os documentos de alto nível sobre como usar as APIs para realizar tarefas específicas. É possível criar uma versão e ser gerada automaticamente para remover o trabalho manual. Os arquivos de marcação resultantes podem ser hospedados como páginas da Web ou exportados como PDF.
A segunda fase vai abordar a documentação do Spider, Autoupdate, Context, Status e Search APIs e a criação dos artigos de caso de uso relevantes usando arquivos Markdown.
A fase final vai abordar o restante das APIs não documentadas e os casos de uso relevantes. No mês passado, pretendo abordar também casos de uso que exigem a invocação de vários componentes de API para realizar uma tarefa.