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
- Redator técnico:
- Saurabh
- Nome do projeto:
- Como estender a documentação do GitHub para a API REST
- Duração do projeto:
- Duração padrão (três meses)
Project description
Objetivo principal
Melhoramos a documentação da API REST baseada em Swagger do OpenMRS para adicionar orientações sobre o uso da API.
Descrição do projeto
A API REST do OpenMRS é um dos principais mecanismos para que os desenvolvedores acessem dados do OpenMRS. Já existe uma documentação gerada automaticamente com base no Swagger da API OpenMRS Webservices e uma documentação estática com base no GitHub. Vamos estender essa documentação com base no GitHub nesta temporada de documentos.
VISÕES GERAIS
Depois de pesquisar um pouco sobre o OpenMRS Talk, como Burke sugeriu, descobri que esse projeto começou em 2017 como um projeto do GSOC. Com Gayan Weerakutti, o objetivo principal era melhorar a documentação existente da API REST do OpenMRS, melhorando a especificação do Swagger e a maneira como ela é gerada para que uma versão melhor da própria documentação do Swagger fosse gerada. Todos os detalhes relevantes alcançados no projeto foram resumidos aqui nesta postagem do OpenMRS e foram bastante úteis.
Em 2019, esse projeto foi reformulado, e deixamos de fazer ajustes na documentação do Swagger para produzir variações. Em vez disso, desenvolvemos uma documentação estática do GitHub que será estendida nesta temporada de Documentos.
A proposta de projeto que pretendo descrever é a seguinte :
- Criação de exemplos em algumas linguagens conhecidas (mencionadas especificamente java e javascript).
- Adição de suporte ao playground para a documentação da plataforma, assim como o recurso ""test drive"" do Swagger.
- Refatorar e melhorar o trabalho feito até agora.
- Encontrar e adicionar os recursos ausentes.
- Adicionamos mais descrição à seção do console dos documentos
DESCRIÇÃO DETALHADA
- Crie exemplos em diferentes idiomas.
Sugiro adicionar exemplos em Java que serão baseados no SDK e, em seguida, adicionar exemplos de retrofit que vão dar mais profundidade à nossa documentação. Adicionar exemplos em mais uma linguagem, como JavaScript, não vai ajudar tanto quanto adicionar exemplos de retrofit, já que usei essas APIs REST enquanto trabalhava no cliente Android do OpenMRS e não havia recursos para consultar sempre que precisava de ajuda para usar os endpoints especificamente para Android. E eu poderia dar alguns exemplos de qualidade aqui, considerando minha experiência com endpoints da API OpenMRS no cliente Android. Vou conversar com meus mentores e trabalhar com base na decisão deles. Além disso, além de adicionar exemplos para as operações suportadas, devemos adicionar exemplos para autenticação com servidores OpenMRS em algumas linguagens de programação. No momento, só temos exemplos de curl para isso.
- Adição de suporte ao Playground para testar exemplos de APIs
Usei esse recurso na documentação do Swagger do OpenMRS hospedado no servidor de demonstração, e é uma ferramenta muito conveniente para incluir em qualquer documentação da API. Pesquisei um pouco e não é tão difícil incorporar a especificação do Swagger-UI à documentação estática atual. Usando os botões de mostrar/ocultar e o código atual da documentação do Swagger. Dessa forma, podemos garantir que o recurso de teste permaneça ativo com as especificações atuais da API. Essa é uma maneira de integrar os recursos do playground à nossa documentação estática atual.
- Refactorizar e melhorar o trabalho feito até agora
Como verificar os exemplos atuais de curl
Esta seção é um dos principais pontos de ênfase deste projeto este ano. No momento, apenas exemplos de curl estão disponíveis nos documentos da API do GitHub, e alguns deles não podem ser executados diretamente no servidor de demonstração para verificação no navegador. Vou testar todos os endpoints atuais e manter um documento simples com várias respostas de exemplos de curl que recebemos ao executar essas solicitações de curl. Usaremos o Postman além do recurso de teste integrado na documentação do Swagger para realizar essa tarefa, se necessário.
Respostas da API ausentes em alguns dos exemplos
Algumas respostas foram adicionadas aos exemplos de curl atuais, mas alguns não têm respostas. Acho que, mesmo que as respostas não sejam detalhadas, o que geralmente acontece com operações como limpeza do recurso, deveríamos ter um exemplo de Resposta da API JSON, embora tenhamos documentado todos os códigos de resposta possíveis e o motivo para recebê-los. Acho que isso tornaria os exemplos na documentação da API mais uniformes!
Exemplos de trabalho ausentes em várias operações
Acho que essa será a parte mais importante da refatoração do trabalho anteriormente realizado na documentação da API. Há exemplos concretos na documentação que podem ser executados diretamente com cURL, mas alguns deles são um pouco abstratos, o que dá uma boa referência a desenvolvedores experientes, mas deixa os novos usuários em estado de incômodo. Como pude concluir nesta postagem na palestra do OpenMRS, bons exemplos são inestimáveis. Além de adicionar exemplos de trabalho, podemos oferecer suporte ao destaque de sintaxe, que não exige muito trabalho, e que vem junto com o Slate, o que facilita bastante o processo, como descobri aqui.
Como Burke enfatizou muitas vezes na postagem, preferindo a simplicidade e a descritividade em documentos em vez de uma boa interface, eu aderiria a esses princípios e tentaria tornar os endpoints documentados anteriormente o mais descritivos possível conversando com os desenvolvedores que estão trabalhando na API OpenMRS Webservices e engajando a comunidade, assim como fiz na postagem da palestra para coletar descrições dos tipos de atributo dos recursos de formulários que não estavam claros para mim no meu PR aqui. Eu realmente trabalharia com base na prioridade, conversando com meus mentores e decidindo quais são as coisas que realmente agregam valor aos documentos e precisam ser realizadas primeiro.
Adicionar casos de uso como um título explícito
Eu vi muitas documentações de API para entender o assunto e notei que todas elas tinham casos de uso como título explícito, embora os casos de uso não sejam explicitamente visíveis, eles são mesclados nas definições e exemplos que seguem após as definições dos recursos e subrecursos. Acho que devemos separar os casos de uso como uma entidade separada na documentação para que os desenvolvedores não precisem pesquisar nas definições que induzem os casos de uso, mas que possam apenas consultá-los.
Encontrar e documentar os recursos ausentes
O estado atual do projeto tem recursos listados aqui, mas ao ver a versão mais recente da documentação do Swagger aqui, pude descobrir muitos recursos que podem ser adicionados ao pacote atual nos documentos de API compatíveis com o GitHub, com a descrição realizada com outros recursos durante a Temporada de Documentos de 2019. Vou discutir os tópicos que precisam ser adicionados aos documentos e adicioná-los adequadamente.
CONCLUSÃO
Faço parte da comunidade do OpenMRS há algum tempo. Sou um colaborador ativo do projeto de cliente Android, em que interajo com as APIs com frequência para interagir com os servidores. Portanto, acho que posso trabalhar neste projeto de extensão dos documentos da API muito bem,já que posso analisar meu trabalho como desenvolvedor e avaliar se ele realmente facilita o trabalho de outros desenvolvedores ou não. Também me familiarizei com as ferramentas usadas para o repositório de documentação fácil de usar hospedado aqui. Fiz várias contribuições a esse repositório para me familiarizar com o repositório e as ferramentas, como o slateUI. Como uma API é considerada tão boa quanto a documentação dela, gostaria de melhorar as APIs REST do OpenMRS um pouco melhorando a documentação.
Vou informar o progresso semanalmente com uma postagem de conversa que ajudará a receber o feedback da comunidade e trabalhar em estreita colaboração com meu mentor e a comunidade para aproveitar ao máximo esse período de documentação.