Como desenvolvedor do apiDoc apidocjs.com – uma ferramenta de documentação para APIs da web RESTful – quero apresentar meu projeto com alguns artigos menores.
apiDoc é OpenSource e pode ser bifurcado em github.com/apidoc/apidoc . Críticas, respostas, problemas e melhorias são bem-vindos!
apiDoc usa node / npm com o padrão para arquivos JavaScript, mas também pode documentar qualquer outra linguagem.
Por que apiDoc?
O problema
Trabalhamos em uma equipe pequena e diferentes programadores desenvolvem Frontend e Backend ao mesmo tempo. É por isso que precisamos de um sistema para documentar a interface de backend.
Primeiro começamos com as ferramentas externas, o problema era que, quando você desenvolve e muda as coisas, você “esquece” de atualizar os documentos, porque você tem que abrir a ferramenta e pesquisar onde alterar o conteúdo.
Em seguida, usamos um arquivo de texto simples (markdown), mas a formatação de tabelas custa muito tempo, é por isso que mudamos para um arquivo Word simples. Mas o problema era o mesmo, quando você muda o código, tem que mudar a documentação em um arquivo externo. E com muitos desenvolvedores você tem estilos de formatação diferentes, arquivos diferentes, …
Javadoc
Eu pessoalmente gostei do estilo de documento Javadoc (phpdoc, jsdoc) e pensei “por que esse estilo não está disponível para uma API RESTful?”
Então eu começo a pesquisar e ver como outras pessoas documentam sua API. Existem muitas ferramentas para testar uma API ou ferramentas online SaaS para documentação, mas elas não resolvem o problema de como o conteúdo vem do meu código para a ferramenta (elas resolvem apenas partes de nosso problema de “Arquivo Word”).
Enquanto desenvolvemos nosso próprio projeto teamspir.it, sinto cada vez mais a necessidade de uma solução como o JSDoc .
Q&D
Finalmente começo a desenvolver o apiDoc, devo admitir: era rápido e sujo, precisava daquela ferramenta mas não tive tanto tempo, devido ao desenvolvimento da nossa própria aplicação.
Portanto, não atire em mim por erros ou código não tão bom 😉 eu tento consertar rapidamente se algo estiver realmente errado.
Começando
Para este artigo, postarei apenas um link para “Primeiros passos” no site:
http://apidocjs.com/#getting-started
Você pode instalar e verificar o exemplo.