Projeto OpenMRS

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
Redator técnico:
Saurabh
Nome do projeto:
Como estender a documentação fácil de usar do GitHub para a API REST
Duração do projeto:
Duração padrão (3 meses)

Project description

Objetivo principal

A documentação da API REST OpenMRS baseada em Swagger foi aprimorada 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 de OpenMRS. Já existe uma documentação da API OpenMRS Webservices gerada automaticamente com base no Swagger e uma documentação estática baseada no GitHub. Queremos ampliar essa documentação baseada no GitHub nesta temporada de documentos.

BREVE VISÃO GERAL

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

Depois, em 2019, o projeto foi reformulado e passamos a usar ajustes na documentação de Swagger para produzir variações sobre ele. Em vez disso, desenvolvemos uma documentação estática compatível com o GitHub que será estendida nesta temporada do Documentos Google.

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

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

DESCRIÇÃO DETALHADA

  1. Criar exemplos em diferentes linguagens.

Sugiro adicionar exemplos em Java que vão ser baseados em SDK e depois adicionar 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 o Android. E eu poderia apresentar alguns exemplos de qualidade aqui devido à minha experiência com endpoints da API OpenMRS no cliente Android. Vou conversar com meus mentores e definir o que for decidido. Além de adicionar exemplos para as operações com suporte, também precisamos adicionar exemplos de autenticação com servidores OpenMRS em algumas linguagens de programação. No momento, temos apenas exemplos de curl para isso.

  1. Adição de suporte ao Playground para testar exemplos de APIs

Usei esse recurso na documentação de swagger do OpenMRS hospedado no servidor de demonstração. É uma ferramenta muito conveniente para ter em qualquer documentação da API. Eu 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 de exibição e ocultação e usar o código da documentação de swagger atual. Desta forma, podemos garantir que o recurso de teste permaneça ativo com as especificações atuais da API. Acredito que podemos integrar os recursos do playground à 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 deste 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, vou usar o Postman, além do recurso de teste integrado na documentação do swagger.

Respostas de API ausentes em alguns dos exemplos

Algumas respostas foram adicionadas aos exemplos de curl presentes, mas alguns deles não têm respostas. Acho que, mesmo que as respostas não sejam detalhadas, o que geralmente é o caso de operações como limpar o recurso, devemos 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 funcionamento 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 que podem ser executados diretamente com cURL, mas alguns deles são um pouco abstratos, o que é uma boa referência para desenvolvedores experientes, mas deixa os iniciantes em um estado de preocupação. Como pude constatar nesta postagem do OpenMRS que bons exemplos não têm preço, além de adicionar exemplos de trabalho, poderíamos dar suporte ao destaque de sintaxe, que não é muito trabalho, e vem agrupado com barreira, o que torna isso muito fácil de fazer, como descobri aqui,

Como Burke enfatizou muitas vezes em sua postagem, preferindo a simplicidade e a descrição nos documentos em vez da boa interface do usuário e da interface brilhante, eu seguiria esses princípios e tentaria tornar os endpoints documentados anteriormente o mais descritivos possível, conversando com desenvolvedores que atualmente trabalham com a API OpenMRS Webservices e envolvendo a comunidade, assim como fiz na postagem da palestra para coletar descrições para os tipos de atributos para os recursos de formulários que não estavam claros para mim. Eu trabalharia com prioridade por prioridade, conversaria com meus mentores e decidiria 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 que não são explicitamente visíveis, eles estão de alguma forma combinados dentro das definições e dos exemplos que seguem após 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, para que os desenvolvedores não precisem apenas procurá-los, apenas buscando os casos de uso.

  1. Encontrar e documentar os recursos ausentes

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

CONCLUSÃO

Já faz um tempo que faço parte da comunidade OpenMRS. Sou um colaborador ativo no projeto Android Client, no qual interajo com as APIs frequentemente para interagir com os servidores. Por isso, sinto que posso trabalhar neste projeto de extensão dos documentos da API muito bem, já que consigo ver meu trabalho como desenvolvedor e avaliar se ele realmente facilita o trabalho de outros desenvolvedores ou não. Conheci as ferramentas usadas no repositório de documentação de fácil utilização hospedado aqui, também fiz várias contribuições para me familiarizar com o repositório e as ferramentas, ou seja, o MRSUI é uma boa documentação para o MRSUI, já que é uma boa documentação para o RESTSUI.

Comunicarei o progresso semanalmente com uma postagem de palestra que ajudará a obter o 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.