Automatic documentation of spring controllers

[petrp]

Hi all,

we're working on a multi-module project based on Spring MVC and REST. We need to document somehow all REST URLs which are accessible in the application.

I wonder, is there a tool (preferably a maven plugin), that could automatically document all controllers? For example, produce a (sorted) list of all mapped paths (taken from @RequestMapping annotations etc.) and interlink them with the JavaDoc documentation of method and classes.

If there is no such tool, would anybody be interested in something like that, if we decide to write it? I suppose it wouldn't be so hard to write, since this information is somehow already produced by the DispatcherServlet (at least what I've seen in a log output).

Best regards,
Petr

[SigmundL]

Hi all,

we're working on a multi-module project based on Spring MVC and REST. We need to document somehow all REST URLs which are accessible in the application.

I wonder, is there a tool (preferably a maven plugin), that could automatically document all controllers? For example, produce a (sorted) list of all mapped paths (taken from @RequestMapping annotations etc.) and interlink them with the JavaDoc documentation of method and classes.

If there is no such tool, would anybody be interested in something like that, if we decide to write it? I suppose it wouldn't be so hard to write, since this information is somehow already produced by the DispatcherServlet (at least what I've seen in a log output).

Best regards,
Petr

Agree, that would be really useful

/S

[scottyfred]

I don't know of a tool that does this. If you want to build something and you need the output integrated with the JavaDoc for the Controller classes, you could implement this as a JavaDoc doclet: http://java.sun.com/j2se/1.5.0/docs/.../overview.html.

I've never done this, but it looks pretty simple.

You would automatically get the Maven plugin this way, since the Maven JavaDoc plugin supports alternative doclets: http://maven.apache.org/plugins/mave...te-doclet.html.

[scottyfred]

The more I thought about this idea, the more I liked it. I got a start on a Javadoc doclet to generate documentation for @RequestMappings, @Controllers, etc. Take a look at it and let me know what you think: http://github.com/scottfrederick/springdoclet.

At the time of this posting, the generated report is not very pretty. I'm working on adding a stylesheet now.

There are a few details I could use some help on, relating to Maven. If any Maven gurus can help figure this out, I would appreciate it.

• The test case doesn't run reliably from Maven (i.e. "mvn test" from the project root). It runs fine from Eclipse or IntelliJ. The problem is that the Spring dependencies aren't in javadoc's classpath when the test is run, even though they are included in the pom.xml with the scope=test.
• Running "mvn javadoc:javadoc" in the sample project works great. Running "mvn site" in the sample project only generates the standard javadoc, not the spring docs, even though it looks to be configured exactly like docs for the maven-javadoc-plugin say it should be (http://maven.apache.org/plugins/mave...te-doclet.html).

Try it out and give me some feedback. If you want to contribute to improving or enhancing this, just let me know.

[SigmundL]

The more I thought about this idea, the more I liked it. I got a start on a Javadoc doclet to generate documentation for @RequestMappings, @Controllers, etc. Take a look at it and let me know what you think: http://github.com/scottfrederick/springdoclet.

At the time of this posting, the generated report is not very pretty. I'm working on adding a stylesheet now.

There are a few details I could use some help on, relating to Maven. If any Maven gurus can help figure this out, I would appreciate it.

• The test case doesn't run reliably from Maven (i.e. "mvn test" from the project root). It runs fine from Eclipse or IntelliJ. The problem is that the Spring dependencies aren't in javadoc's classpath when the test is run, even though they are included in the pom.xml with the scope=test.
• Running "mvn javadoc:javadoc" in the sample project works great. Running "mvn site" in the sample project only generates the standard javadoc, not the spring docs, even though it looks to be configured exactly like docs for the maven-javadoc-plugin say it should be (http://maven.apache.org/plugins/mave...te-doclet.html).

Try it out and give me some feedback. If you want to contribute to improving or enhancing this, just let me know.

Nice, and in Groovy too. Checking it out.

/S

[SigmundL]

Gram seems to be of use for you:

http://groovy.codehaus.org/Gram

/S

[yincrash]

I like this idea!

[vw729]

The Spring log file contains the controller and URL mapping information during a server starting up period. I guess that you can parse the log file and write the information into another file as your controller documentation.