Generate HTML documentation from XSD using Maven plugin

Question

After days of searching, I have yet to find a decent HTML generator that I can use as a Maven reporting plugin. I've tried using JAXB and Javadoc, but it is not really a clean solution, since it forces me to use jaxb-javadoc tags and what's worse, it forces me to duplicate the documentation that is already present.

My comments look like this:

<xs:annotation>
  <xs:documentation>My comments</xs:documentation>
</xs:annotation>

I'd rather not use <xs:appinfo> tags if I can avoid it.

I don't want to install a tool/application on a specific machine to generate HTML. I am willing to use the JAXB and Javadoc approach as last-ditch effort, but it's not picking up comments unless they are tagged as:

<xs:annotation>
  <xs:appinfo>
    <jxb:class> <!-- Or :property -->
      <jxb:javadoc>My comments</jxb:javadoc>
    </jxb:class>
  <xs:appinfo>
</xs:annotation>

which is ugly and it doesn't seem to work for XSD groups (I've tried both <jxb:class> and <jxb:property>).

Is there any Maven reporting plugin out there that can do this for me? I am also willing to use Xalan or some other transformation framework (as long as it is through Maven), but I am not that keen on creating the stylesheet myself.

Any tips out there?

What I’m looking for is to simply abstract XML Schema elements as messages, which is most often the case for RESTful-WS (as an example). Generating HTML documentation which allows application developers, laymen and business developers to share a common knowledge base to understand a protocol or API. None of these are interested in the finer points of XML Schemas (targets, QNames, namespaces, etc), they just want to know:

• What does request X look like (an XML element)?
• What fields can/must I set (max/minOccurs)?
• What information is available in response Y?
• For a restricted field, what enum values are allowed?

Javadoc goes a long way to answer these questions, but in order for JAXB to pick it up, the XSD must be tagged in a certain way (using appinfo tags), as well as polluting the original XSD with JAXB namespace. By the way, I generate both C, C++ and Java bindings from the XSD, so the XSD is the master document.

WADL doesn’t quite fit the bill here because even that is too technical and its purpose is mainly to be consumed by machines, not people.

Apart from maybe changing a color schema in the generated HTML, I was baffled to learn that there isn’t a turnkey solution for this. Almost all of them require a local installation of some sort (apart from the JAXB and Javadoc Maven plugin I use now) which goes against the grain of Maven’s concept of portable builds. All organizations I worked for have either made their peace with JAXB/Javadoc or simple developed their own transformation tool to generate HTML.

Answer 1

Did you look at: http://www.filigris.com/docflex-xml/xsddoc/ ?

It does everything you want:

• It generates first-class HTML documentation (both single-file and framed multi-file) by any number of XML schemas of any complexity
• It also can generate the same documentation in RTF
• It inserts in the generated docs all the comments/annotations found in your XML schemas (including even those preformatted with XHTML, which can be rendered in both HTML and RTF output)
• It does have a Maven plug-in
• It appears on the first page in Google on every search query related to XML schema/XSD documentation generator
• There is even a support forum where you can ask any specific questions and receive the answer the same day: http://www.filigris.com/forum/

So, what's wrong with all this?

BTW, if you don't like to pay for it, you can use it for free. Not all features will be available, however, the Maven plug-in will work.

I am also willing to use Xalan or some other transformation framework (as long as it is through Maven), but I am not that keen on creating the stylesheet myself.

I suggest to take a look at these threads:

1. How to convert xsd to human readable documentation? -- the comprehensive discussion of the matter; there is little one can add to all mentioned there.
2. Can XML be documented using Doxygen, Sandcastle, or other documentation generators? -- strange question but correct reply
3. Using xslt to transform multiple xml schema documents -- here, the XML schema guru (Michael Kay) also suggests that "manipulating raw schema documents using XSLT is difficult because there are so many different ways of writing the same thing in XSD"