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

Question

关闭。这个问题不符合Stack Overflow guidelines .它目前不接受答案。












想改进这个问题？将问题更新为 on-topic对于堆栈溢出。

3年前关闭。




Improve this 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 文档，允许应用程序开发人员、外行和业务开发人员共享公共(public)知识库以了解协议(protocol)或 API。这些都不对 XML Schema 的细节(目标、QNames、命名空间等)感兴趣，他们只是想知道:

请求 X 是什么样的(一​​个 XML 元素)？

我可以/必须设置哪些字段(max/minOccurs)？

响应 Y 中有哪些信息可用？

对于受限字段，允许使用哪些枚举值？

Javadoc 在回答这些问题方面有很长的路要走，但为了让 JAXB 接受它，必须以某种方式标记 XSD(使用 appinfo 标记)，以及使用 JAXB 命名空间污染原始 XSD。顺便说一句，我从 XSD 生成 C、C++ 和 Java 绑定(bind)，因此 XSD 是主文档。

WADL 在这里并不完全符合要求，因为即使这样也太技术性了，而且它的目的主要是供机器使用，而不是人。

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

Answer 1

你看过:
http://www.filigris.com/docflex-xml/xsddoc/
?

它做你想做的一切:

它生成一流的 HTML 文档(单文件和框架多文件)
通过任意数量的任意复杂性的 XML 模式

它还可以在 RTF

中生成相同的文档

它会在生成的文档中插入在您的 XML 模式中找到的所有注释/注释(甚至包括使用 XHTML 预先格式化的那些，它们可以在 HTML 和 RTF 输出中呈现)

它确实有一个 Maven 插件

它出现在与 XML 架构/XSD 文档生成器相关的每个搜索查询的 Google 第一页

甚至还有一个支持论坛，您可以在其中提出任何具体问题并在同一天收到答案:http://www.filigris.com/forum/

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

BTW，如果你不喜欢付费，你可以免费使用。并非所有功能都可用，但是，Maven 插件可以工作。

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.

我建议看看这些线程:

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 中有很多不同的方式来编写相同的东西”