Certamente, durante o desenvolvimento da API, as dificuldades com a documentação apareceram mais de uma vez: ou ela não existe, então não exibe o comportamento descrito no código.
Do ponto de vista do desenvolvedor, escrever documentação (somente interno) não leva menos tempo do que escrever o próprio código. Isso é familiar? Então seja bem-vindo ao gato.
Existe algum problema?
Nossa equipe desenvolve a API há muito tempo, que é a base do nosso produto, mas na época não havia usuários ativos, então ninguém viu a necessidade de documentar algo para uso externo. Como todas as equipes, começamos com documentação interna - primeiro um método, depois outro. Em nosso espaço no Confluence, você pode encontrar uma dúzia de outras páginas que exibem informações bastante detalhadas - que tipo de método API, que caminho de consulta possui, quais parâmetros e o que obtemos na saída.
Tudo ficaria bem, mas o código está constantemente mudando e crescendo, as necessidades dos negócios estão mudando. Juntamente com as alterações de código, as APIs podem mudar, o que inevitavelmente leva a alterações nessas páginas. Bem, se é uma página e apenas 1 vez. E se houver mais mudanças?
Chegamos a uma solução (nossa própria bicicleta), tanto quanto possível, enquanto participamos das atividades habituais do desenvolvedor, para não pensar em escrever e atualizar a documentação interna.
Algumas soluções
Existem diferentes opções de como o código e sua especificação podem ser interconectados, mas para mim eu distingo dois:
- Código primeiro, especificação a seguir
- Especificação primeiro, código próximo
Começarei com o segundo, como na opção menos adequada para nós.
Especificação primeiro, o código a seguir é sobre geração de código, com base na especificação, ou seja, o código não existe até você escrever a especificação.
O exemplo mais simples é o Swagger Codegen.
Nossa empresa possui equipes que usam essa abordagem em seus produtos, mas, no nosso caso, não era muito adequada. No momento em que fomos confrontados com uma necessidade, já tínhamos escrito muitos métodos de API, portanto, para fins de documentação, não queríamos mudar radicalmente os processos de desenvolvimento - primeiro escrevemos rascunhos, depois codificamos e somente depois a descrição da especificação.
Código primeiro, especificação a seguir - tudo é simples, primeiro escrevemos o código, depois a especificação. Mas então surgiu a questão - e se não queremos fazer movimentos desnecessários para que a especificação seja gerada?
Vários aplicativos em nossa empresa usam essa abordagem, mas não é particularmente automatizada - os métodos de API são ponderados com todos os tipos de anotações, com base nos quais a especificação foi gerada. Mas essas mesmas anotações geralmente não correspondem à realidade, porque as necessidades e capacidades do aplicativo estão crescendo e mudando.
"Você é um programador" , disse a mim mesma, e decidi escrever um pequeno protótipo que me permitiria não escrever todo esse lixo de rotina.
Executando a próxima tarefa e escrevendo o enésimo teste funcional, percebi que já possuímos todas as informações para a especificação.
Temos testes funcionais que contêm quase todas as informações necessárias:
- Como está sendo chamado
- O que é chamado (parâmetros, corpo, cabeçalhos, etc.)
- Qual resultado é esperado (código de status, corpo da resposta)
Por que não fazer sua própria bicicleta?
Quase tudo o que costumamos escrever nas especificações que temos. O caso de código pequeno neste caso.
Como nossa aplicação é em php, a reflexão veio em meu auxílio. Usando um pouco de mágica de reflexão, coletamos todos os métodos de API disponíveis, coletamos dados de testes funcionais, extraímos dados sobre autorização e seu tipo. Das anotações usuais aos métodos, obtemos a descrição do próprio método. Depois de misturar tudo isso, temperar com recursos específicos da estrutura usada em nossas soluções, em algumas semanas obtemos uma solução que praticamente não requer tempo adicional do desenvolvedor.
A geração de uma especificação é apenas o primeiro passo - você precisa obter a documentação da especificação que pode ser fornecida por um desenvolvedor externo. Um dos requisitos para a documentação é que ela seja apresentada em vários idiomas, mas, no momento, apenas geramos documentação em inglês. Até o momento, basta, mas será necessário conectar um mecanismo para receber transferências ao nosso esquema de geração de especificações.
O problema que foi originalmente resolvido. Mas com esta solução, existem muitos riscos:
- Preço apoiar sua própria bicicleta
- Extensão da funcionalidade necessária
- Atualização e sincronização de traduções
Esses riscos devem ser lembrados e, se começarem a funcionar, aja.