生成由Servlet支持的API的文档的好方法？

Question

Does anyone know of a good tool or strategy for generating the external documentation for a collection of java servlets? I could, of course, use my favorite rich text editor to generate an independent document. But it might be more likely to be maintained if the documentation is in the source code. Unfortunately, the problem is a bit unstructured. Each servlet is a Java class, but that's the end of official structure. Inside the servlet's doGet method, it consumes some set of URL-encoded parameters in a completely unstructured way, and produces some sort of output, say a web page or a JSON object.

Javadoc does a decent job of documenting the code itself, but I want to document the API seen by clients of my service.

In javadoc style, I could imagine putting documentation on the class, and maybe define some annotation to put on the doGet method's local variables that represent parameters. But I'd still need specialized processing -- I don't want what javadoc would defaultly produce.

(Yes, I've seen this other question What's the best way to generate a REST API's documentation? , which has no encouraging answers, but I thought I'd try rephrasing the question slightly.)

Answer 1

I'd say you should add a couple of properties to your servlets - add a parameters property and a response_details property (or something similar). Then require those as part of your servlet signature; they can contain strings in some popular text format (Markdown, ReST?) which describes the input and output of that servlet.

You can then just introspect the servlet classes, run the resulting strings through the appropriate existing processor for whatever markup format you use, and viola, docs.

You could add more structure to what's actually required in those properties if you wanted - for instance, parameters could be required to be a Map<String,String> or something like that. It's all up to you.