Générer des documents API via des commentaires de code

Question

J'utilise aglio pour générer ma documentation API. J'écris actuellement la démarque brute pour cela en fonction de la spécification API Blueprint. Je me demande s'il existe un moyen de générer la démarque par des commentaires directement dans le code. Est-ce que quelqu'un est au courant d'un moyen de le faire?

Answer 1

Techniquement, il est possible. Selon votre langue et les frameworks utilisés. Par exemple, dans Ruby, on peut utiliser RSpec to generate API Blueprint.

Je ne suis pas familier avec un outil qui fait quelque chose de similaire pour Node.js (par exemple en utilisant Express.js DSL). Lors de l'écriture d'un outil générant un blueprint, il est possible d'éviter de créer manuellement le blueprint et d'utiliser Matter Compiler à la place. Cet outil (Ruby gem) convertit JSON ou dans l'arbre de mémoire (AST) en API Blueprint.

Notez que personnellement, je déconseille de générer de la documentation à partir du code. Au lieu de cela, je considère API Blueprint comme un contrat qui peut être utilisé pour test your API implementation. En ce sens, générer un plan à partir du code revient à générer des tests à partir du code (pour tester le même code).

Answer 2

Je ne suis pas au courant de l'agilo, mais une autre solution alternative est de générer la documentation de l'API en utilisant maven site plugin.

<plugin> 
    <artifactId>maven-site-plugin</artifactId> 
    <groupId>org.apache.maven.plugins</groupId> 
    <version>${maven-site-plugin.version}</version> 
    <configuration> 
     <locales>en,fr</locales> 
    </configuration> 
    </plugin> 

Vous pouvez écrire le fichier apt qui contient les détails de l'API et plus tard, vous pouvez exécuter Maven pour générer la doc. Il génère le bon doc. Ce qui est très populaire et beaucoup de gens dans l'industrie en utilisant largement.

Plus de détails à http://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html