Question

经过几天的搜索，我还没有找到一个体面的HTML生成器，我可以将其用作Maven报告插件。我尝试过使用JAXB和Javadoc，但它并不是一个干净的解决方案，因为它迫使我使用jaxb-javadoc标签，更糟糕的是，它迫使我复制已经存在的文档。

我的评论如下：

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

如果可以避免，我不想使用<xs:appinfo>标签。

我不想在特定计算机上安装工具/应用程序来生成HTML。我愿意使用JAXB和Javadoc方法作为最后的努力，但除非它们被标记为：

，否则不会收集评论。

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

这是丑陋的，它似乎不适用于XSD群组（我已经尝试了<jxb:class>和<jxb:property>）。

有没有Maven报告插件可以为我做这个？我也愿意使用Xalan或其他一些转换框架（只要通过Maven），但我并不热衷于自己创建样式表。

有任何提示吗？

我正在寻找的是简单地将XML Schema元素抽象为消息，这通常是RESTful-WS的情况（作为示例）。生成HTML文档，允许应用程序开发人员，非专业人员和业务开发人员共享通用知识库，以了解协议或API。这些都不是对XML Schema（目标，QNames，名称空间等）的细节感兴趣，他们只是想知道：

请求X看起来像什么（XML元素）？
我可以/必须设置哪些字段（max / minOccurs）？
回复Y有哪些信息？
对于受限制的字段，允许使用哪些枚举值？

Javadoc在很长一段时间内回答了这些问题，但为了让JAXB选择它，必须以某种方式标记XSD（使用appinfo标签），以及使用JAXB名称空间污染原始XSD。顺便说一句，我从XSD生成C，C ++和Java绑定，因此XSD是主文档。

WADL并不适合这里的法案，因为即使这样做太技术化，其目的主要是机器而不是人。

除了可能在生成的HTML中更改颜色模式之外，我感到困惑的是要知道没有一个交钥匙解决方案。几乎所有这些都需要某种本地安装（除了我现在使用的JAXB和Javadoc Maven插件），这与Maven的可移植构建概念背道而驰。我所工作的所有组织要么与JAXB / Javadoc保持和平，要么简单地开发自己的转换工具来生成HTML。

Answer 1

你看过了吗： http://www.filigris.com/docflex-xml/xsddoc/ ？

它可以做你想做的一切：

它生成一流的HTML文档（单文件和框架多文件）任意复杂的任意数量的XML模式
它也可以在RTF中生成相同的文档
它在生成的文档中插入XML模式中的所有注释/注释（包括那些预先格式化为XHTML的注释/注释，可以在HTML和RTF输出中呈现）
它有一个Maven插件
它出现在Google的第一页上与 XML架构/ XSD文档生成器相关的每个搜索查询
甚至还有一个支持论坛，您可以在其中提出任何具体问题，并在同一天收到答案：http://www.filigris.com/forum/

那么，这一切有什么问题？

顺便说一句，如果你不想付钱，你可以免费使用它。并非所有功能都可用，但是，Maven插件可以正常工作。

我也愿意使用Xalan或其他一些转换框架（只要通过Maven），但我并不热衷于自己创建样式表。

我建议看看这些主题：

How to convert xsd to human readable documentation? - 对此事的全面讨论;那里提到的所有人都没有什么可以添加的。
Can XML be documented using Doxygen, Sandcastle, or other documentation generators? - 奇怪的问题但是回复正确
Using xslt to transform multiple xml schema documents - 这里，XML模式大师（Michael Kay）也建议“使用XSLT操纵原始模式文档很困难，因为在XSD中有很多不同的方法来编写相同的东西”

使用Maven插件从XSD生成HTML文档

1 个答案: