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:
- OpenMRS.org
- Redator técnico:
- batbrain7
- Nome do projeto:
- Documentação da API REST OpenMRS
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Vou dividir minha proposta em seções diferentes e seguir o fluxo, como a documentação da API do Google Maps e a documentação da API do GitHub.
Além disso, gostaria de propor uma estrutura readme para a documentação da API 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 com uma introdução rápida sobre a API, sobre OpenMRS e sobre como a API é usada e o que vem em seguida.
Como conseguir a chave de API e a autenticação necessária para fazer a solicitação de API. Será um exemplo de amostra dos tipos de autenticação presentes na API e das chaves e dos valores que precisam estar presentes para ela, além dos tipos de valores aceitos que correspondem à chave nessa parte. Um exemplo de código em qualquer linguagem ajuda e explica como escrever cabeçalhos e formatos de resposta, além de outros parâmetros de consulta na API.
São mencionados os tipos de resposta buscados pela API, os tipos de JSON ou qualquer outro tipo de resultado retornado pelas APIs.
As diferentes rotas de API e quais parâmetros precisam ser enviados com essas rotas, cabeçalhos e outras coisas. Cada API será auxiliada 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.
Esta é uma ideia geral de como a documentação será definida para a API REST.
O cronograma do projeto é o seguinte :
1o de agosto - 1o de setembro
Conheça melhor meu mentor e discuta com mais detalhes o nível da documentação necessária em diferentes partes da base de código. Também discuto como fazer isso na documentação de nível baixo e de alto nível. Também vou passar esse tempo entendendo a base do código e estudar os conceitos para documentá-los melhor.
Semanas 1 e 2
Vou atualizar e estender o guia dos colaboradores. Vou melhorar a documentação sobre como criar o código-fonte. Também adicionarei uma seção de documentadores sobre como novos colaboradores podem ajudar na documentação. Vamos analisar a documentação da API, começar pela introdução e adicionar a autenticação.
Semanas 3 e 8
Adicionarei as rotas e respostas de 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ção da documentação da API usando links, por exemplo, um índice vinculado a uma documentação de API longa, e divida-a ainda mais com bases diferentes, como seções de código, visão geral, parâmetros e endpoints raiz.
Semana final
Usarei a última semana para preparar meu relatório final do trabalho realizado durante meu período de documentação de 12 semanas. Também vou usar esse tempo para analisar e finalizar a documentação.