Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- OWASP Foundation
- Redator técnico:
- sshniro
- Nome do projeto:
- Melhoria na documentação da API ZAP
- Duração do projeto:
- Duração padrão (três meses)
Project description
O ZAP tem uma API extremamente poderosa que permite fazer quase tudo possível pela interface para computador. No entanto, para usar as APIs de maneira eficaz, é necessário entender bem a interface. Isso ocorre porque a maioria das APIs se correlaciona diretamente à interface do usuário do proxy do 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 poucas informações sobre os parâmetros envolvidos e dão menos oportunidades para a comunidade contribuir com a documentação da API. Além disso, a interface da Web (versão para computador) usada no ZAP também usa a lista de APIs geradas automaticamente para invocação. Essa 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). Portanto, nesta proposta, sugiro uma nova abordagem para documentar as APIs.
A ideia é recriar os documentos da API com as especificações da OpenAPI 3. A OpenAPI oferece um framework comum para desenvolvedores, testadores e DevOps criarem, manterem e testarem APIs. As especificações da OpenAPI preenchidas para o ZAP podem ser usadas para gerar automaticamente os arquivos do Swagger. Os arquivos Swagger podem ser integrados à interface do aplicativo da Web (app para computador) do ZAP para fornecer aos usuários um cliente de teste de API avançado.
Além da documentação da API, pretendo 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 atualizada de APIs RESTful combinando a documentação escrita à mão com a documentação de API gerada automaticamente produzida pelo Swagger. Os resultados serão semelhantes à documentação da API do GitHub. (https://developer.github.com/v3/). Este documento escrito à mão contém 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 precisa consultar a API continuamente para saber o status dela. Portanto, esses documentos de alto nível vão discutir quais APIs devem ser usadas para realizar uma ação e apontar para os documentos do Swagger gerados automaticamente para leitura adicional.
Um total de mais de 380 APIs foram implementadas no proxy do ZA. Inicialmente, minha proposta é documentar todas as APIs com uma descrição delas e informações sobre os parâmetros e as respostas de sucesso e falha. Já foi feita uma POC de amostra, e detalhes adicionais 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 API aberta para o recurso de verificação ativa e as APIs principais (mais de 150). Paralelamente à criação dos arquivos do Swagger, também será criada a documentação de caso de uso relevante/ documentos de alto nível sobre como usar as APIs para realizar tarefas específicas. Isso pode ser controlado por versão e gerado automaticamente para remover o trabalho manual, e os arquivos Markdown resultantes podem ser hospedados como páginas da Web ou exportados como PDF.
A segunda fase vai abranger a documentação de Spider, Autoupdate, Context, Status, APIs de pesquisa e a criação dos artigos de casos de uso relevantes usando arquivos Markdown.
A fase final vai abranger o restante das APIs não documentadas e os casos de uso relevantes delas. No mês passado, pretendo abordar também casos de uso que exigem a invocação de vários componentes de API para executar uma tarefa.