Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
Templates
Examples
Integrations
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - WSDLDoc - WSDL Documentation Generator

  1. What is DocFlex/XML WSDLDoc?
  2. What you can generate with it
  3. What is processed/documented
  4. Documentation Features
  5. Possiblity of unlimited cutomizations
  6. Getting Started
  7. Template Set Overview
  8. Examples

1.  What is DocFlex/XML WSDLDoc?

A powerful WSDL/XSD documentation generator that will help you to create a single HTML or RTF documentation for any number of both WSDL and XSD (XML schema) files with the possibility of automatic inclusion of XSD diagrams generated by either Altova XMLSpy or Oxygen XML Editor.

It is implemented in the form of “WSDLDoc” template set for DocFlex/XML.

DocFlex/XML is a software system for development and execution of high quality documentation and report generators from any data stored in XML files. WSDLDoc is an application of it. For more details, please see: DocFlex/XML | Overview, Features.

WSDLDoc was derived from the early XSDDoc template set (an implementation of XML Schema Documentation Generator) and inherits all its functionality.

Currently, it is made of 114 templates, which include two main templates (controlled by more than 650 parameters):

WSDLDoc template set is found in 'templates/WSDLDoc/' subdirectory of DocFlex/XML archive or installation.
It is ready to use. Please read Getting Started!

2.  What you can generate with it

Framed HTML Documentation

Using FramedDoc.tpl main template, you can generate a multi-framed HTML documentation by any number of WSDL 1.1 / W3C XML Schema definition (XSD) files. It looks very similar to JavaDoc and provides most detailed and easy accessible information about all WSDL definitions, XML schema components as well as any interconnections between them.

Here you can see some samples of such a documentation (click on a screenshot to view the real HTML):

The following functionality is supported: Please, take a look also at WSDLDoc | Examples page for more samples of HTML documentation generated from various large WSDL / XML schema files found on Internet.

Single-File HTML Documentation

PlainDoc.tpl is another main template designed primarily to generate RTF documentation. However, just by setting the output format to “HTML”, you can equally generate a single HTML file with the same content. This is a demo documentation generated in that way (click on the screenshot to see it):

RTF Documentation

Using PlainDoc.tpl main template, you can generate a sigle-file RTF documentation by any number of WSDL 1.1 / W3C XML Schema definition (XSD) files. It is built of the same basic blocks as the framed HTML documentation (which are actually generated by the same subtemplates) with a few additional features.

These screenshots show pages of a demo RTF documentation (click to enlarge):

The following features/functionality are supported:
  • Main Sections (click on each link to see a corresponding screenshot):
  • Page Header/Footer
    The page header shows the information about the current section, the footer - the documentation short title and the current page number.
  • Page Number References
    Although the generated RTF includes hyperlinks (similar to those in HTML), they have no use in the printed form. So, many hyperlinks are supplemented with the page number of the link's target shown like: link text [page number]
  • Grouping of component details (WSDL definitions / XSD components):
    • by namespaces
    • by source files
    • all together
  • Rendering of HTML/XHTML tags in WSDL descriptions / XSD annotations / template parameters
    You can use XHTML tags in your WSDL descriptions and XSD annotations (see below) to format the text, define lists and tables, include images etc. Equally, HTML tags can be used in some titles and descriptions passed via template parameters.

    Although RTF is incompatible with HTML, all of the specified HTML/XHTML markup will be rendered with the appropriate formatting features of RTF (including lists, tables and insertion of images).

  • Selectively forcing to start from a new page the documentation sections of particular types

PDF Documentation

DocFlex/XML currently generates no PDF directly. However, you can produce quite decent PDF from RTF using some converters. For instance, the following has been created with MS Word 2016 from the original RTF (click on the screenshot to download the PDF file, 4.6 MB):

3.  What is processed/documented

Any number of input WSDL/XSD files

  • Including all XML schemas embedded in WSDL (within <wsdl:definitons>/<wsdl:types> element).
  • Even when the same XML schema (defining the same namespace) is embedded in multiple WSDL files documented together, all of those instances will be documented correctly. There will be no mess out of it.

All referenced WSDL/XSD files

  • Correct processing of all <wsdl:import>, <xs:import>, <xs:include>, <xs:redefine> elements found across all involved WSDL/XSD files.
  • Including when one embedded XML schema imports another embedded XML schema located in the same WSDL file.
  • Automatic loading and processing (i.e. inclusion in the documentation scope) all directly/indirectly referenced WSDL/XSD files.
You just need to specify only the root WSDL/XSD files of your project. Everything referenced from them will be loaded automatically!

All interconnections between WSDL/XSD

  • Hyperlinks from WSDL messages to the details of XSD elements/types describing the message data.
  • In XSD element/type details, the list of all WSDL definitions where they are used.
  • Copy the annotations of XSD elements/types to the documentation of those WSDL messages (and even operations) where they are used.

XHTML tags in your descriptions/annotations

Below is a demo of what can be achieved using XHTML markup in XML schema annotations. On the left you can see the XML source of an XML schema, whose annotations are heavily laden with XHTML markup (including insertion of images). The next is the framed HTML documentation generated by that schema (click on screenshots to see the actual HTML):

The last two sreenshots show pages of the RTF documentation generated by that schema (click to enlarge). Here, you can also download a PDF converted from that RTF: HumanEvolution-xsddoc.pdf

See Also:

Support of XML Catalogs

XML catalog(s) may be used in a large WSDL/XML schema project to avoid referencing separate WSDL/XSD files from each other by direct file names. You may also want to use an XML catalog when some WSDL/XSD files involved in your project are located differently as they are specified in other WSDL/XSD files.

See Also:

4.  Documentation Features

This section highlights some advanced features, which you rarely find in other documentation generators. That makes our tool so special!

Highly navigable framed HTML documentation

The idea comes from Javadoc:

In the top-left “Overview Frame” you select some large-scale scope, e.g. a namespace or an XML schema. In the bottom-left “List Frame” you select a particular XSD component within the selected scope. The “Detail Frame” shows the details of the selected item (e.g. component). That structure allows you to quickly find what you need without disturbing the current view of the detail document.

See Also: Framed HTML Documentation

Dense layouts: more information in less space

Our template technology (see DocFlex/XML | Features) allows for fast programming of complex table-based grid layous.

Using it, it is possible to generate such things as shown on the left screenshot (click to enlarge).

You may think: What's special here? Just yet another page of some documentation... But it uses three grid layouts! If that technique was not applied, the information printed on that page would occupy 2-3 pages instead!

Abundance of cross-links

When you look at a documentation generated by our tool, you can see a lot of hyperlinks. Everything seems to be a hyperlink!

Cross-links are produced by matching sets of special keys generated for both link source and destination. The keys represent actual data being linked. Their generation is specified in templates along with the generation of the corresponding pieces of output. In that way anything can be cross-linked together. At that, if a particular set of keys cannot be matched, an alternative set of keys can be specified as well. That means, when the primary target is absent, the link can go to some alternative location related to the link source.

For instance, when in a reproduced XML source the value of some attribute is the name of some XSD component, that value is linked to the component detail. But when the detail is absent, the link can go to a corresponding item in some component summary:

In RTF documentation intended for printing, some cross-links can be emulated with page number references that appear in square brackets after the linked item, as visible in the above screenshot.

See Also: DocFlex/XML | Features | Hypertext | Cross-Reference Links

Support of any XML schema design patterns

How elements are defined in XML schema is a subject of so called “schema design patterns”. The difference in many ways comes down to whether the local elements are used and how much. (For instance, some XML schemas define only one global element - the root one, all others are defined locally). So, a single approach to document local elements is at the same time a single way of documenting different schema design patterns. This includes:

Adding extensions to local element names

Local elements are those element components that are defined locally within other XSD components (e.g. complexTypes or groups).

Using local elements you can define in an XML schema several element components with the same name but different content. That's OK to verify an XML file (for which XML schemas are typically used). But it creates a problem for documenting. Since the main purpose of the documentation is to show relations between components, all element components eventually surface globally. For instance, when you have a list of some element components that share particular properties, very likely it will include several local elements with the same name. If nothing is done about that, you will see repeating names in that list, which may look quite confusing.

We solve that problem by adding some extensions to the repeating element names, which make those elements unique. The extensions are generated according to:
  • The element's possible parent in an XML document (its containing element), when there can be only one of such
  • The element global type (see also below)
  • The XSD component, where the element is defined

Here is how the element name extensions look (the grey text):

Unifying local elements by type

When a single name is used for several element components that means they share something common. Sometimes that 'common' comes down to the element type. For instance, in many XML schemas instead of defining a single global element and reference to it from many locations, multiple identical local elements are declared like this:

<xs:element name="someName" type="typeName"/>

You've got lots of local element components that define effectively the same thing. So, instead of flooding the documentation with repeating element names, why not to document all those local elements (with the same global type) as a single one? We shall call it unified local element and its name extension (when necessary) will be just the name of that global type.

Here's how it works:

On the left you can see a documentation generated with such unification. On the right, all local elements are documented straight as they are. Click on the screenshots to view the docs.

We think the first documentation (on the left) is much easier to understand.

List of containing elements

When you look at details of an XSD element component (produced by any doc-generator), you will typically see which children an XML element represented by that component may have. But it is equally interesting to know the possible parents of an XML element! Specifically, the list of those XSD element components, whose content model includes the given one.

Here's an example of such a list (click on the screenshot to see it within the documentation):

Inclusion of XSD diagrams

Possibility of automatic inclusion of XSD diagrams generated by either XMLSpy or Oxygen XML, with the support of all diagram hyperlinks. For more details, please see: The diagrams can be generated for any XML schemas both found in XSD files and embedded in WSDL. At that, only XSD functionality of either XMLSpy or Oxygen XML is used.

5.  Possiblity of unlimited cutomizations

Template parameters

Since all content and formatting of the generated documentation is programmed entirely in templates, the numerous options and switches, which normally control traditional documentation generators, now simply become template parameters.

Template parameters are easy to introduce and access in templates, so there may be lots of them. That allows you to adjust the generated output within a greate range of various details, thereby squeezing the most from what is already programmed in the existing templates without changing anything in them.

On the other hand, to avoid overwhelming the user with too many unimportant settings, many template parameters inherit or derive their default values from other top-level parameters. So, you actually need to change only a few of them. The entire parameter set is organiaze in a tree, which makes it easier to understand and navigate. That tree is displayed in the Parameter Insector as shown below.

WSDLDoc is controlled by more than 600 parameters, which you can specify in Parameter Insector invoked from the generator GUI (when you click «Params» button with one of the main templates selected):

Alternatively, you can specify any template parameters through Java command line using -p option.

See Also:

Generator options

Generator options are more traditional things. They control particular features of the selected output generator (that is what is hardcoded in Java code).

Generator options are separated from templates. They do not depend on the selected template as well as their settings are not used in templates at all. That's because templates are designed to be mostly independent of the particular output format. Only some general assumptions about the output format are accounted, for instance, whether it supports pagination and has page numbers.

Which particular generator options are available depends on the selected output format, which currently may be HTML, RTF and TXT (plain text). In the generator GUI, after you have selected the destination output format, you can click «Options» button, which will invoke Format Option Inspector. Here you can see all options available for the given format and specify them. This screenshot shows the HTML Option Inspector:

Alternatively, you can specify any generator options (along with template parameters) through Java command line using -o option.

See Also:

Using custom CSS styles

You can apply also your own CSS styles to change how the generated documentation looks.

On the left you can see a documentation generated with the default formatting as specified in WSDLDoc templates. On the right, the same documentation generated with the application of a custom CSS stylesheet. (Click on the screenshots to view the docs.)

That stylesheet is provided along with the WSDLDoc templates as the file: {docflex-xml}/templates/WSDLDoc/azure-theme.css

How to specify it is shown in the HTML Option Inspector screenshot above. You should set:
  • Output | Generate named rules = all
  • Output | Generate named rules | Custom rules file = Stylesheet file path name

Note that the possibility to use any CSS stylesheets is available only under the “DocFlex/XML SDK” license (which cover the Template Designer).

See Also:

Modifying templates with Template Designer

If template parameters and CSS styles are not enough, you can modify the templates themselves using the Template Designer:

Template Designer is a highly sophisticated GUI used to design/edit templates. It represents the template both in the form template components, which it is made of, and the output those components would generate.

This screenshot shows WSDLDoc/lib/navbar.tpl template open in the Template Designer (click on the screenshot to see in full size). That template generates the navigation bar that appears in the framed HTML documentation.

The dialog over the designer pane represents template properties. The selected tab shows the list of formatting styles used in this template.

Note that all content and formatting you see in the generated output is programmed entirely in templates. In that respect, DocFlex templates are not exactly “templates” in traditional sense (which typically serve to arrange how some output fragments readily provided by the generator are placed in the result output). Rather, DocFlex templates are more akin to XSLT scripts. For more details, please read: DocFlex Technology | Overview.

Template Designer is covered by the separate “DocFlex/XML SDK” license, which you need to acquire along with “DocFlex/XML WSDLDoc” license, if you want to modify WSDLDoc templates.

See Also:

6.  Getting Started

WSDLDoc License

Running WSDLDoc templates requires a separate license, which you should receive by e-mail. If you don't have it yet, you can

The license comes as a single 'docflex-xml-wsdldoc.license' file that should be stored in one of the locations:

  • The WSDLDoc template set directory (along with FramedDoc.tpl main template):

    {docflex-xml}/templates/WSDLDoc/

  • DocFlex/XML 'lib' directory (near 'docflex-xml.jar' file):

    {docflex-xml}/lib/

    here '{docflex-xml}' denotes your DocFlex/XML installation directory.

In those locations the license file is looked for by default.

Notes:

  • Alternatively, you can specify any other location of your license file directly on the generator or template designer command line using the -license option.
  • Instead of separate WSDLDoc trial, you can

    for DocFlex/XML software together. You will receive a single 'docflex-xml.license' file containing all trial licenses (including for WSDLDoc). You should install that file in {docflex-xml}/lib/ directory. Then, you won't need to request separate licenses for any other features (e.g. template designer, integrations etc.) you want to try.
See Also:

How to run WSDLDoc?

Here is the detailed instruction from the very start:
  1. Download the DocFlex/XML archive from the downloads page.
  2. Unpack it in some directory, e.g.:

    C:\docflex-xml-1.10

    In further explanations, we shall refer to that directory as '{docflex-xml}'.

  3. Obtain and install “DocFlex/XML WSDLDoc” license as described above.
  4. Edit:

    {docflex-xml}/generator.bat

    to specify the 'JAVA_HOME' variable according to the location of Java 1.4.x - 8.x installed on your system (the latest Java version is preferable as it may be the fastest!)

    If you don't have one of those Java versions installed on your system, you can freely download and install the most recent Java Runtime Environment (JRE) version from Java Technology web-site: http://www.oracle.com/technetwork/java/

  5. Run that generator.bat. You will see the Generator Dialog like shown on this screenshot:

  6. In the “Template” field, select
  7. In the “XML File(s)” field, specify one or many WSDL/XSD files, by which you want to generate the documentation.

    This field must contain one or several file specifications, which may be either:
    • local file pathname or pathname pattern
    • URL (e.g. http://www.w3.org/2001/XMLSchema.xsd)
    Notes:
    • Multiple file specifications must be separated with spaces.
    • When a file specification contains spaces itself, it must be enclosed in double quotes.
    • You can combine any specification types together.
    • The "pathname pattern" is an Ant-style pattern for local file pathnames. See: DocFlex/XML | Documentation | Running Generator | ... | Using file pathname patterns.
    • In case of URL, the generator will try to download such a file directly from the Internet (or elsewhere). This, however, can be redirected using an XML catalog.

  8. In the “Output format” field, select HTML or RTF format.

    RTF will work only with PlainDoc.tpl template!

  9. Click “Run” button to start the generation.

    Once all source WSDL/XSD files have been loaded, the generator enters into the estimation phase. Lots of processing is being done during that, however, you will see only "Scanning data source, please wait..." message on the progress bar. On large input data this phase may take some time. Please wait! After that, the generator passes into the generation phase. The progress bar will show what's being generated.

    You can stop the generator at any time during any phase by clicking <Cancel> button.

How to include XSD diagrams?

DocFlex/XML is able to work with any kind of diagrams (i.e. inserting them automatically in the generated output). That is supported on the level of templates, along with the generation of hypertext imagemaps.

But, currently, DocFlex/XML provides no diagramming engine of its own. Instead, it includes integrations with two most popular XML editors that do generate XSD diagrams:

Each integration works as follows:
  1. It feeds the XML schema file to the given third-party software and forces it (via its open API or command-line options) to generate its own XML schema documentation, the most simplified one, however with diagrams.

    In case of XMLSpy, the generated output is an HTML file + diagram images. Oxygen XML makes mater even simpler by generating (along with diagram images) some intermediate XML file (with the known structure) that can be converted further into any kind of documentation.

  2. Then, the output produced by the third-party tool is parsed and the diagrams + imagemaps are extracted from it.
  3. They are used as an addition to the initial XML schema file and fed to the DocFlex templates in some abstract form.
When the XML schema is embedded in WSDL file, it is extracted into a separate temporary XSD file, which is equally processed by the third-party software. At that, only XSD capabilities of that software are used -- no WSDL functionality is required from it.

The advantage of such integrations is that when you are the user of one of those XML editors, you will get in the documentation generated by DocFlex the same diagrams as you see in your XML editor.

Case of XMLSpy

If you have XMLSpy (http://www.altova.com/xmlspy/) installed on your system, here is how to get the XMLSpy Integration work:
  1. Go to the subdirectory:

    {docflex-xml}/integrations/XMLSpy/

    here '{docflex-xml}' denotes the directory where you installed DocFlex/XML.
  2. Find generator.bat in that directory and edit it to specify:
    • Java location (e.g. c:\Program Files\Java\jre8)
    • XMLSpy installation directory (e.g. c:\Program Files\Altova\XMLSpy2016)

    For more details about this, please read the README file found in the same directory: {docflex-xml}/integrations/XMLSpy/README.html

  3. Run that generator.bat.
  4. Everything else is the same as described in How to run WSDLDoc.
Notes:

Case of Oxygen XML

If you have Oxygen XML Editor (http://www.oxygenxml.com) installed on your system, here is how to get the Oxygen XML Integration work:
  1. Go to the subdirectory:

    {docflex-xml}/integrations/OxygenXML/

    here '{docflex-xml}' denotes the directory where you installed DocFlex/XML.
  2. Find generator.bat in that directory and edit it to specify:
    • Java location (e.g. c:\Program Files\Java\jre8)
    • Oxygen XML installation directory (e.g. c:\Program Files\Oxygen XML Editor 18)

    For more details about this, please read the README file found in the same directory: {docflex-xml}/integrations/OxygenXML/README.html

  3. Run that generator.bat.
  4. Everything else is the same as described in How to run WSDLDoc.
Notes:

How to integrate with Ant/Maven?

A demo about that you can find in your DocFlex/XML installation:
{docflex-xml}/integrations/ant/
{docflex-xml}/integrations/maven/

Note: All demo make-files are prepared for XSDDoc. Just replace in them 'XSDDoc' with 'WSDLDoc' to make everything work with WSDLDoc as well.

See also:

7.  Template Set Overview

This section is published on a separate page: DocFlex/XML | WSDLDoc | Templates. Here is its table of contents:

8.  Examples

This section is published on a separate page: DocFlex/XML | WSDLDoc | Examples. Here is its table of contents:

  1. HTML Documentation
  2. RTF / PDF Documentation

Copyright© 2016 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.