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:
- OpenMRS.org
- Redator técnico:
- batbrain7
- Nome do projeto:
- Documentação da API REST do OpenMRS
- Duração do projeto:
- Duração padrão (três meses)
Project description
Vou dividir minha proposta em diferentes seções e seguir o fluxo, como a documentação da API Google Maps e da API do GitHub.
Além disso, eu também gostaria de propor uma estrutura leia-me para a documentação da API que é feita pelo realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Pessoalmente, achei essa documentação muito fácil de entender e usar.
Minha proposta consiste principalmente em três seções :
Uma seção que daria uma breve introdução sobre a API, sobre o OpenMRS e sobre como a API é usada e o que vem depois disso.
Como conseguir a chave de API e a autenticação necessária em geral para fazer a solicitação de API. Ela consistirá em um exemplo de amostra dos tipos de autenticação presentes na API e das chaves e valores que precisam estar presentes para ela, além dos tipos de valores aceitos que correspondem à chave naquela parte. Um exemplo de código em qualquer idioma ajudaria a esclarecer como gravar os cabeçalhos, os formatos de resposta e outros parâmetros de consulta na API.
Os tipos de respostas que são buscados pela API, os tipos de JSON ou qualquer outro tipo de resultado retornado pelas APIs precisam ser mencionados.
As diferentes rotas de API e quais parâmetros precisam ser enviados com elas, os cabeçalhos e outras coisas. Cada API será assistida por exemplos de código em algumas linguagens que descrevem como a solicitação é feita ao escrever o código para ela, além dos códigos de erro gerais que podem ser encontrados com cada API.
Essa é uma ideia geral de como a documentação será definida para a API REST.
O cronograma do projeto é o seguinte :
1º de agosto a 1º de setembro
Conhecer meu mentor e discutir em mais detalhes o nível de documentação necessário em diferentes partes da base de código e também discutir o nível de detalhamento da documentação de nível baixo e alto. Também vou usar esse tempo para entender a base de código e estudar os conceitos para poder documentar melhor.
Semanas 1 e 2
Vou atualizar e estender o guia para colaboradores. Vou melhorar a documentação sobre como criar o código-fonte. Também vou adicionar uma seção sobre como os novos colaboradores podem ajudar na documentação. Vou estudar a documentação de diferentes APIs e começar com a introdução e adicionar a autenticação para a API.
Semanas 3 e 8
Vou adicionar as rotas e respostas da API, além de alguns exemplos de código para cada tipo de API (pode haver tipos semelhantes de APIs).
Semanas 9 e 10
Adicione a estrutura da documentação da API usando links, ou seja, um índice vinculado para a documentação longa da API e divida-o em uma base diferente, como seções de código, visão geral, parâmetros, endpoints raiz.
Semana final
Vou usar a semana final para preparar meu relatório final do trabalho realizado durante o período de documentação de 12 semanas. Também vou usar esse tempo para revisar e finalizar a documentação.