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

1.  What is DocFlex/XML WSDLDoc?

A powerful WSDL/XSD documentation generator that will help you to create a unified HTML or RTF documentation (with XSD diagrams) for any number of both WSDL and XSD (XML schema) files.

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 and inherits all its functionality. It includes two main templates:

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

HTML Output

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

SingleDoc.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 Output

RTF Documentation

Using SingleDoc.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:

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

All 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

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:

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 screenshots 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

For how to use XHTML markup, please see: DocFlex/XML | XSDDoc | FAQ | Formatting annotations with XHTML.

In case of WSDL descriptions, it is all the same. Everything written for <xs:documentation> is applicable to <wsdl:documentation>.

The processing of XHTML tags is controlled in WSDLDoc by the parameter group: “Processing | Descriptions | Tags | XHTML”, which is the same as “Processing | Annotations | Tags | XHTML” parameter group in XSDDoc.

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

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:

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 DiagramKit, XMLSpy, Oxygen XML with the support of all diagram hyperlinks. The diagrams can be generated for any XML schemas both found in XSD files and embedded in WSDL.

For more details, please see:

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 Inspector as shown below.

WSDLDoc is controlled by more than 600 parameters, which you can specify in Parameter Inspector 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/css/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 covers 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

You can try WSDLDoc right now, without any registration! Just download DocFlex/XML zip-archive and follow the instructions below.

By default, everything will work in demo mode. You will be able to generate a reduced documentation (including diagrams) by any your input WSDL/XSD files. If they are small enough, that will be actually the complete documentation, which you can use for free! For further details, see Licensing.

How to run WSDLDoc?

Running on Windows

  1. Download the DocFlex/XML archive from the downloads page.
  2. Unpack it in some directory, e.g.:

    C:\docflex-xml

    which we shall refer as '{docflex-xml}'.

  3. Edit:

    {docflex-xml}/bin/generator.bat

    to specify the 'JAVA_HOME' variable according to the location of Java 8.x (or later) installed on your system.

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

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

  5. In the «Template» field, select
  6. 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.

  7. In the «Output format» field, select HTML or RTF format.

    RTF will work only with SingleDoc.tpl template!

  8. Click «Run» button to start the generation.

    If you have not installed any licenses, you will see this dialog:

    Just click OK to continue.

    This message notifies you, that everything will work in demo mode. It means that WSDLDoc will process all your input WSDL/XSD files, however fully document only limited number of components. XSD diagrams will be generated by DiagramKit too, as many as it's allowed by WSDLDoc demo limits. If those limits are not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limits were exceeded.

    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.

Running on macOS

Notes:
  • DocFlex/XML was tested on macOS Mojave (10.14)
  • For everything to work, you need to have Java installed on your Mac (so that 'java' command is available in the Terminal). You can download Java for Mac from the Oracle website: http://www.oracle.com/technetwork/java/
  1. Unpack the downloaded DocFlex/XML archive at some location (e.g. on Desktop), which we shall designate as {docflex-xml}.
  2. Go to {docflex-xml}/bin/macOS directory (open it with the Finder).

    The doc-generator (Template Processor) is launched by generator.command shell script file. To be able running it, first you need to assign it with the executable privilege as follows:

    Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag generator.command from the Finder into the Terminal window). Then, press Enter. Now, you can run generator.command from the Finder just by clicking twice on it.

    When you run generator.command, the Generator Dialog should show up like on this screenshot:

  3. Anything else is the same as in case of Windows.

Running on Linux

  1. Unpack the downloaded DocFlex/XML archive at some location, which we shall designate as {docflex-xml}.
  2. Go to {docflex-xml}/bin/linux directory. The doc-generator (Template Processor) is launched by generator.sh shell script file.

    Edit generator.sh to specify the JAVA_HOME variable according to the location of Java 8.x (or later) installed on your system. Edit also the file "Permission" properties to allow it to be executed by Linux.

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

  3. Anything else is the same as in case of Windows.

How to include XSD diagrams?

Diagrams are generated by a diagramming plugin.

Diagramming plugins are particular implementations of Element Image Provider. Since DocFlex/XML itself is mostly about data-mining in XML files and generating some human-readable texts from the found results, it has little intersection with diagramming. So, generation of any diagrams needs to be implemented separately for every particular documentation task, where they are required. Since the latter is the job of a particular template application, the diagramming plugin serves as its functional extension and both need to interact.

DocFlex/XML currently includes three different diagramming plugins able to generate XSD diagrams:

Plugin

Description

DiagramKit implements DocFlex/XML native diagramming engine (independent on any third-party software). It creates beautiful XSD diagrams, which can be generated/inserted simultaneously along with the documentation generated by WSDLDoc (with the support of all possible hyperlinks).

All diagrams visible in all WSDLDoc examples (including on this page) were generated by DiagramKit!

DiagramKit is the default DocFlex/XML diagramming plugin and will be active immediately when you run WSDLDoc as decribed above. However, it is covered by a separate license.

See Also:
If you have a license for Altova XMLSpy (http://www.altova.com/xmlspy/), you can turn it into a diagramming engine for DocFlex/XML using XMLSpy Integration.

Here is how to get it work:

  1. Go to the subdirectory:

    {docflex-xml}/integrations/XMLSpy/

    where '{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\XMLSpy2018)
    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.
See Also:
DocFlex/XML | Integrations | XMLSpy
If you have a license for Oxygen XML Editor (http://www.oxygenxml.com), you can turn it into a diagramming engine for DocFlex/XML using OxygenXML Integration.

Here is how to get it 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.
See Also:
DocFlex/XML | Integrations | Oxygen XML

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

Demo Mode

Once you have download DocFlex/XML archive, you can run WSDLDoc immediately and see what it is. You don't need to request any trial and register anywhere!

By default, everything will work in demo mode. It means that all your input WSDL/XSD files will be fully processed, however fully documented will be only limited number of components. XSD diagrams will be generated as well by any diagramming plugin you choose (DiagramKit by default) and as many as it's allowed by WSDLDoc demo limits. What exactly the demo limits are depends on particular main templates (as well as some metrics).

If those limits are not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limits were exceeded. Anyway, the result documentation will be minimally distorted, to allow you to evaluate how everything will look under the full license. Any documentation generated in demo mode is yours. You may use it for free as you wish.

Template Designer will work in demo mode as well. You will be able to run it, investigate some functionality, but unable to save any created/modified templates.

See Also:

Trial License

The standard package of trial licenses (see below) unlocks full functionality of WSDLDoc / DiagramKit / Template Designer. You will be able to evaluate how everything works, generate the complete documentation by all your WSDL/XSD files. It will include all possible details (according to the settings specified in template parameters). All XSD diagrams will be generated as well.

But there will be some limitations:

You can request trial license by clicking this button:

Then, you will be redirected to Try | Trial License page with “DocFlex/XML (essential)” preselected in the «Product» field.

“DocFlex/XML (essential)” means that you get in fact not a single but a package of trial licenses (corresponding all full ones): all of them together in a single 'docflex-xml.license' file, which you will receive by email.

The license file should be saved in DocFlex/XML 'lib' directory (near 'docflex-xml.jar' file):

{docflex-xml}/lib/

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

See Also:

Full Licenses

The whole functionality described on this page is covered by three different full licenses:

License

Description

DocFlex/XML WSDLDoc Unlocks all functionality implemented in WSDLDoc templates. In particular, you will be able to:
  • Process any number of input WSDL/XSD files and generate complete documentation by them in any supported output format.
  • Use FramedDoc.tpl main template to generate to generate framed HTML documentation.
  • Use SingleDoc.tpl main template to generate single file HTML or RTF documentation.
  • Use all parameters controlling WSDLDoc templates to customize the generated WSDL/XSD documentation within a huge range of possibilities.
  • Format your WSDL descriptions and XML schema annotations with XHTML tags and reproduce that formatting both in HTML and RTF output.
  • Inserting images in your annotations using XHTML <img> tags (supported both in HTML and RTF output).
  • Modify WSDLDoc templates as much as you need using Template Designer (provided that you also have a separate DocFlex/XML SDK license).
  • Run any your custom templates derived from WSDLDoc.
DocFlex/XML DiagramKit Unlocks all functionality implemented in DiagramKit. Allows you to generate XSD diagrams and automatically insert them into documentation generated by WSDLDoc (with the support of all possible diagram hyperlinks).
DocFlex/XML SDK You need this license if you want to heavily customize the generated documentation (e.g. change some colors, fonts, layouts, look & feel, add new functionality etc). In particular, this license covers:
Please note that neither commercial template applications themselves (e.g. WSDLDoc) nor diagramming plugins are covered by this license!

See Also:

Which Licenses You Need - Use Cases

You don't have to purchase all full licenses listed above – only those required for your particular goal 1):

Your goal

The license(s) you need

  1. DocFlex/XML WSDLDoc
  1. DocFlex/XML WSDLDoc
  2. DocFlex/XML DiagramKit 2)
  1. DocFlex/XML WSDLDoc
  2. DocFlex/XML SDK
  1. DocFlex/XML WSDLDoc
  2. DocFlex/XML DiagramKit 2)
  3. DocFlex/XML SDK

1) You can order any combination of those licenses starting from Shop page.
2) Instead of DiagramKit, you can equally use/license other diagramming plugins: XMLSpy Integration or OxygenXML Integration.


Copyright© 2018 Filigris Works. Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.filigris.com or e-mail to: contact@filigris.com