Generate API docs via code comments [closed]

Question

Closed. This question is seeking recommendations for books, tools, software libraries, and more. It does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.

Closed 5 years ago.

Improve this question

I'm using aglio to generate my API documentation. I'm currently writing the raw markdown for this based on the API Blueprint spec. I'm wondering if there's a way to generate the markdown via comments directly in the code. Is anyone aware of a way to do this?

Answer 1

Technically it is possible. Depending on your language and used frameworks. For example, in Ruby, one could use RSpec to generate API Blueprint.

I am not familiar with any tool that does something similar for Node.js (e.g. using Express.js DSL).

When writing a tool that is generating a blueprint, one can avoid authoring the blueprint manually and use Matter Compiler instead. This tool (Ruby gem) converts JSON or in memory tree (AST) into API Blueprint.

Note that I personally advice against generating documentation from the code. Instead I consider API Blueprint as a contract that can be used to test your API implementation.

In this sense generating a blueprint from the code is like generating tests from the code (to test the very same code).

Answer 2

I am not aware of the agilo, but other alternate solution is to generate the API documentation using 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>

You can write the apt file which contains the details of the API and later you can run maven to generate the doc. It generates the nice doc. Which is very popular and many people in industry using extensively.

More details at http://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html