如何查看 HTML 标记中的 xsd:documentation？
我正在使用 IBM Rational Software Architect (RSA) 从 UML 模型生成 SOAP 服务的 WSDL/XSD。 RSA 允许您使用丰富的格式来记录模型中的类和属性。
例如，我有关于 Trailer 类的以下文档：
轮式车辆，设计用于由其他车辆牵引 车辆。已知的亚型包括：
- 商队
- BoxTrailer
- 船拖车
当 UML 模型转换为 WSDL/XSD（使用开箱即用的 UML 到 WSDL 转换）时，格式将保留为 xsd:documentation 元素内的 HTML 标记：
<xsd:complexType name="Trailer">
<xsd:annotation>
<xsd:documentation><p>
A&nbsp;wheeled <strong>Vehicle</strong> that is designed for&nbsp;towing by another <strong>Vehicle.</strong> Known
subtypes include:&nbsp;
</p>
<ul>
<li>
<strong>Caravan</strong>
</li>
<li>
<strong>BoxTrailer</strong>
</li>
<li>
<strong>BoatTrailer</strong>
</li>
</ul></xsd:documentation>
</xsd:annotation>
</xsd:complexType>
不幸的是，这真的很难阅读，我一直在寻找（没有运气）一个可以查看带有 HTML 标记文档的 WSDL/XSD 的程序。
XmlSpy 2008 无法做到这一点，RSA 也无法做到这一点（这有点令人惊讶，因为它首先生成了 XSD），我尝试过的任何 Web 浏览器也无法做到这一点。
我确实编写了一个 JET 模板，它从模型中提取文档并输出为 HTML，并且我可能可以编写一些 XSLT 来执行与 XSD 类似的操作，但我希望有一个程序（最好是免费的）可以查看HTML 格式的文档。
本质上，我希望能够告诉我们的 Web 服务的使用者，如果他们想阅读文档，他们可以在 X 程序中查看 WSDL - 有人知道对此的最佳解决方案吗？
编辑： 感谢您的建议，但我想我有一个解决方案！我没有意识到 RSA 可以将 WSDL 导出为 HTML（右键单击 WSDL，导出，HTML）。生成的 HTML 具有每个架构元素的图形视图、每个元素的文档以及原始源，并且所有内容都超链接在一起。
最重要的是，文档的格式再次丰富！一个小警告是 ;nbsp 出现在 HTML 输出中。这似乎是因为＆符号在 HTML 中被转义：
相反，它应该是
我将更新我的模型到模型转换以确保将 ;nbsp 替换为真实空格（我不认为文档中需要不间断空格），因此生成的 WSDL/XSD 永远不会有他们。
I am generating WSDL/XSD for SOAP services from a UML model using IBM Rational Software Architect (RSA). RSA allows you to document the classes and attributes in the model using rich-formatting.
For example, I have the following documentation on a Trailer class:
A wheeled Vehicle that is designed for towing by another
Vehicle. Known subtypes include:
- Caravan
- BoxTrailer
- BoatTrailer
When the UML model is transformed to WSDL/XSD (using the out-of-the-box UML to WSDL transform), the formatting is preserved as HTML markup inside the xsd:documentation element:
<xsd:complexType name="Trailer">
<xsd:annotation>
<xsd:documentation><p>
A wheeled <strong>Vehicle</strong> that is designed for towing by another <strong>Vehicle.</strong> Known
subtypes include:
</p>
<ul>
<li>
<strong>Caravan</strong>
</li>
<li>
<strong>BoxTrailer</strong>
</li>
<li>
<strong>BoatTrailer</strong>
</li>
</ul></xsd:documentation>
</xsd:annotation>
</xsd:complexType>
Unfortunately, this is really hard to read and I've been searching (with no luck) for a program that can view WSDL/XSD with documentation in HTML markup.
XmlSpy 2008 can't do it, RSA can't do it (which is a bit surprising, as it generated the XSD in the first place), neither can any web browser I've tried.
I did write a JET template that extracted the documentation from the model and outputted to HTML, and I could probably write some XSLT to do something similar from the XSD, but I was hoping there's a program out there (ideally free) that could view the documentation as HTML.
Essentially, I'd like to be able to tell the consumers of our web service that they can view the WSDL in X program if they want to read the documentation - does anybody know the best solution to this?
Edit:
Thanks for the suggestions, but I think I have a solution! I didn't realise that RSA can export a WSDL to HTML (right-click on WSDL, export, HTML). The generated HTML has a graphical view of each schema element, the documentation for each element, as well as the original source, and everything is hyperlinked together.
Most importantly, the documentation is richly-formatted again! One small caveat is that the ;nbsp's appear in the HTML output. This seems to be because the ampersand is escaped in the HTML:
Instead it should be
I will update my model-to-model transform to ensure that the ;nbsp's are replaced with real spaces (I don't believe I'll need non-breaking spaces in the documentation), so the generated WSDL/XSD won't ever have them.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（4）
我非常怀疑标准的 xml/xsd 编辑器是否可以解释 html 标签并生成适当的文档。 Oxygen XML 编辑器在理解和转换 XML 实体（如 < 等）方面做得不错，但 HTML 标签和实体保持原样。下面是设计视图中的屏幕截图。
I highly doubt if the standard xml/xsd editors can interpret the html tags and generate appropriate documentation. Oxygen XML Editor does a decent job of understanding and converting the XML entities (liket < etc) but HTML tags and entities are left as is. Below is the screen shot in design view.
请注意，如果标记没有转义，它绝对必须是格式良好的 XML 片段，否则文档元素将导致您的架构格式错误。这也适用于 HTML 实体！如果文档包含（未转义的）实体引用（5 个预定义的 XML 实体除外），那么您的架构必须包含外部 DTD 引用，或者具有定义替换内容的嵌入式 DTD该实体的文本。在您的情况下，文档包含
如果您有有机会的话，尝试在不逃避标记的情况下包含文档，并确保其格式良好。否则，您可能需要处理文档两次：1）解析架构并提取文档2）再次解析文档文本（可能是 HTML，而不是 XML）。
The type of
<xs:documentation>is<xs:any>so you should actually be able to include your documentation without escaping the markup, provided that it is a well formed XHTML fragment instead of HTML. I guess some XML Schema tools would be capable to interpret the embedded XHTML and show it as formatted text.Do note that if the markup is not escaped it absolutely must be a well formatted XML fragment or the documentation element will cause your schema to be malformed. This applies also to HTML entities! If the documentation contains an (unescaped) entity reference (other than the 5 pre-defined XML entities), then your schema either must contain an external DTD reference or have an embedded DTD that defines what is the replacement text of that entity. In your case the documentation contains an
If you have a chance, try to include the documentation without escaping the markup and make sure that it will be well formed. Otherwise you probably need to process the documentation twice: 1) parse the schema and extract documentation 2) parse the documentation text again (possibly as HTML, not XML).
我已经使用最新版本的 QTAssistant 尝试过此操作，并且仅在架构帮助面板中显示如下；我已经提出了网格视图的功能请求，以及文档生成器的工作原理相同。这是你所期待的吗？
帮助面板显示在图形/图表视图中选择的架构对象的注释。要显示帮助面板，请按 F1。
I've tried this with the latest build of QTAssistant and it shows like this in the Schema Help Panel only; I've put a feature request for the grid view, as well as the documentation generator to work the same. Is this what you're expecting?
The help panel shows the annotation of the schema object that is selected in the Graph/Diagram view. To display the help panel press F1.
此问题已在 RSA 8.0.4 中修复 - 其中现在支持使用纯文本导出到 WSDL/XSD（以及按类型排序模式的选项，然后按名称排序）按字母顺序排列！）。
要查看从 RSA 早期版本中的 UML 模型生成的 WSDL/XSD 中的文档，最简单的解决方案是使用 RSA 将 WSDL/XSD 导出为 HTML。您可以通过右键单击 WSDL/XSD，选择导出，然后选择 HTML 来完成此操作。
生成的 HTML 具有每个架构元素的图形视图、每个元素的文档以及原始源，并且所有内容都超链接在一起。
最重要的是，文档（在 WSDL/XSD 中几乎无法阅读）再次具有丰富的格式！需要注意的一点是，RSA 文档编辑器插入的
;nbsp也会出现在 HTML 输出中。这似乎是因为 & 符号不仅在 WSDL/XSD 中被转义（这很好），而且在 HTML 中也被转义（不好！）：相反，它应该是
< code>
一个简单的解决方法是在生成 HTML 之前将 WSDL/XSD 中的所有
This issue is fixed in RSA 8.0.4 - which now supports exporting to WSDL/XSD with plain text (as well as an option to sort the schema by type, then name alphabetically!).
To view the the documentation in a WSDL/XSD generated from a UML model in prior versions of RSA, the easiest solution is to export the WSDL/XSD as HTML using RSA. You can do this by right-clicking on the WSDL/XSD, selecting export, then selecting HTML.
The generated HTML has a graphical view of each schema element, the documentation for each element, as well as the original source, and everything is hyperlinked together.
Most importantly, the documentation (that's virtually unreadable in the WSDL/XSD) is richly-formatted again! One small caveat is that the
;nbsp's that RSA's documentation editor inserts also appear in the HTML output. This seems to be because the ampersand is not only escaped in the WSDL/XSD (which is good), but also in the HTML (bad!): Instead it should be
A simple workaround to this is to replace all
's in the WSDL/XSD with real spaces before generating the HTML.