How to view xsd:documentation that is in HTML markup?

Question

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>&lt;p&gt;
    A&amp;nbsp;wheeled &lt;strong&gt;Vehicle&lt;/strong&gt; that is designed for&amp;nbsp;towing by another &lt;strong&gt;Vehicle.&lt;/strong&gt; Known
    subtypes include:&amp;nbsp;
&lt;/p&gt;
&lt;ul&gt;
    &lt;li&gt;
        &lt;strong&gt;Caravan&lt;/strong&gt;
    &lt;/li&gt;
    &lt;li&gt;
        &lt;strong&gt;BoxTrailer&lt;/strong&gt;
    &lt;/li&gt;
    &lt;li&gt;
        &lt;strong&gt;BoatTrailer&lt;/strong&gt;
    &lt;/li&gt;
&lt;/ul&gt;</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.

Answer 1

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.

Answer 2

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   entity reference. Probably easiest will be to replace such entities with the corresponding Unicode character/text or with character references (use   for  )

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).

Answer 3

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.

Answer 4

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.