Projeto OpenMRS

Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:
OpenMRS
Redator técnico:
Saurabh
(link em inglês)
Nome do projeto:
Extensão da documentação amigável do GitHub para a API REST
Duração do projeto:
Duração padrão (3 meses)

Project description

Objetivo principal

Aprimore 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 OpenMRS é um dos principais mecanismos para os desenvolvedores acessarem dados do OpenMRS. Já existe uma documentação baseada em Swagger gerada automaticamente para a API OpenMRS Webservices e uma documentação estática baseada em GitHub também. Devemos estender essa documentação baseada em GitHub nesta temporada de documentos.

BREVE VISÃO GERAL

Depois de pesquisar um pouco sobre o OpenMRS Talk, como Burke sugeriu, soube que esse projeto começou em 2017, como um projeto do GSOC. Com Gayan Weerakutti, o principal objetivo era melhorar a documentação existente da API REST OpenMRS, aprimorando a especificação Swagger e aprimorando a forma como a especificação Swagger é gerada para que uma versão melhor da documentação do swagger seja gerada. Todos os detalhes relevantes realizados no projeto foram resumidos aqui nesta postagem de palestra do OpenMRS e foram muito úteis.

Então, em 2019, este projeto foi reformulado e deixamos de fazer ajustes na documentação de Swagger para produzir variações. Em vez disso, desenvolvemos uma documentação estática compatível com o GitHub que será estendida nesta temporada de Documentos.

Então, um resumo da proposta de projeto atual que pretendo descrever é :

  1. Criar exemplos em algumas linguagens populares (especificamente Java e javascript).
  2. Foi adicionado suporte ao playground para a documentação de barreira, assim como o recurso ""testar"" do Swagger.
  3. Refatorar e melhorar o trabalho feito até agora.
  4. Encontrar e adicionar os recursos ausentes.
  5. Adicionando um pouco mais de descrição à seção do console da documentação

DESCRIÇÃO DETALHADA

  1. Criar exemplos em diferentes linguagens.

Sugiro adicionar exemplos em Java baseados em SDK e depois exemplos de retroajuste que vão dar mais profundidade à nossa documentação, já que adicionar exemplos em mais uma linguagem, como JavaScript, não será tão útil quanto adicionar exemplos de retrofit, já que usei essas APIs REST ao trabalhar no cliente Android OpenMRS e não havia recursos para consultar sempre que eu precisava de ajuda para usar os endpoints especificamente para Android. E eu poderia fazer alguns exemplos de qualidade aqui devido à minha experiência em mexer com endpoints da API OpenMRS no cliente Android. Vou discutir isso com meus mentores e trabalhar no que for decidido. Além de adicionar exemplos das operações aceitas, também precisamos adicionar exemplos para autenticação com servidores OpenMRS em algumas linguagens de programação. No momento, temos apenas exemplos de curl para isso.

  1. Adicionar suporte ao Playground para testar exemplos de APIs

Usei esse recurso na documentação do Swagger do OpenMRS hospedado no servidor de demonstração. É uma ferramenta muito conveniente para ter em qualquer documentação da API. Pesquisei um pouco aqui e não é tão difícil incorporar a especificação da IU Swagger na documentação estática atual. Usar as alternâncias "Halloween" e usar o código de documentação atual do Swagger. Dessa forma, podemos até garantir que o recurso de teste permaneça ativo com as especificações atuais da API. É uma maneira de integrar os recursos do playground em nossa documentação estática atual.

  1. Refatorar e melhorar o trabalho feito até agora
Como verificar os exemplos de curl atuais

Esta seção é uma das principais ênfases deste projeto neste ano. No momento, há apenas exemplos de curl nos documentos da API do GitHub, alguns dos quais não podem ser executados diretamente no servidor de demonstração para serem verificados diretamente 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. Se necessário, além do recurso integrado de teste incluído na documentação do Swagger, vou usar o Postman.

Respostas de API ausentes em alguns dos exemplos

Algumas respostas foram adicionadas aos exemplos de curl atuais, mas alguns deles não têm respostas. Acho que mesmo que as respostas não sejam detalhadas, o que normalmente acontece com operações como limpeza de recursos, 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 consegui-los, acho que isso tornaria os exemplos em toda a documentação da API mais uniformes.

Faltam exemplos de trabalho em várias operações

Acho que essa será a parte mais importante da refatoração do trabalho realizado anteriormente 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 iniciantes em dúvida. Como entendi nesta postagem do OpenMRS, os bons exemplos não têm preço. Além de adicionar exemplos de trabalho, podemos dar suporte ao destaque de sintaxe, que não é muito trabalhoso e vem empacotado com barreira, o que facilita a implementação.

Como Burke enfatizou muitas vezes em sua postagem, preferindo a simplicidade e a descrição em documentos em vez de uma boa interface de usuário e uma interface brilhante, eu admitia esses princípios e tentava tornar os endpoints documentados anteriormente o mais descritivos possível, conversando com desenvolvedores que estão atualmente trabalhando na API OpenMRS Webservices e envolvendo a comunidade, assim como fiz na postagem da palestra para coletar descrições dos tipos de atributos para os recursos de RP que não estavam claros para mim. Eu realmente trabalharia em questões de 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

Vi muitas documentações de API apenas para me entender e vi que todas tinham casos de uso como uma manchete explícita, embora tenhamos casos de uso em que não são explicitamente visíveis, eles estão um pouco fundidos nas definições e nos exemplos que seguem as definições dos recursos e sub-recursos. Acho que devemos nos esforçar para separar os casos de uso como uma entidade separada na documentação, de modo que os desenvolvedores não precisem apenas pesquisá-los.

  1. Encontrar e documentar os recursos ausentes

    O estado atual do projeto tem recursos listados aqui, mas ao consultar a versão mais recente da documentação do swagger aqui, pude descobrir muitos recursos que podem ser adicionados ao conjunto atual de recursos nos documentos de API compatíveis com o GitHub, com a descrição realizada com outros recursos durante a temporada de documentos de 2019. Discutiremos os tópicos que precisam ser adicionados aos documentos e os incluirei adequadamente.

CONCLUSÃO

Faço parte da comunidade do OpenMRS há algum tempo. Sou um colaborador ativo no projeto Android Client, onde interajo com as APIs frequentemente para interagir com os servidores. Por isso, sinto que posso trabalhar muito bem neste projeto de ampliação dos documentos da API, já que posso ver meu trabalho como desenvolvedor e avaliar se ele realmente facilita o trabalho de outros desenvolvedores ou não.

Comunicarei o progresso semanalmente com uma palestra que ajudará você a receber feedback da comunidade e a trabalhar em estreita relação com meu mentor e comunidade para aproveitar ao máximo esse período de documentação.