FlexDoc/XML - WSDLDoc (WSDL Documentation Generator)

WSDLDoc is included in FlexDoc/XML archive ready for downloads now!

  1. What is FlexDoc/XML WSDLDoc?
  2. What you can generate with it
  3. What is processed/documented
  4. Documentation Features
  5. Possibility of unlimited customizations
  6. Getting Started
  7. Licensing

1. What is FlexDoc/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 FlexDoc/XML.

FlexDoc/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: FlexDoc/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 'WSDLDoc' subdirectory of FlexDoc/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 easily 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 single-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

FlexDoc/XML currently generates no PDF directly. However, you can produce quite decent PDF from RTF using some converters. For instance, the following samples have been created with MS Word 2019 from the original RTF (click on the screenshot to view/download the PDF files: 4.3 MB / 8.9 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: FlexDoc/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

Dynamic search functionality

WSDLDoc supports the dynamic search that works similar as in the modern Javadoc. All identifiers like WSDL/XSD definition/component names, attributes etc. are indexed.

The dynamic Search-Box powered by JQuery UI can be embedded into the Navigation Bar at the top and bottom of each detail page as shown on the screenshot (click to view in full size).

The search-box is also available on the special Search Page that shows the search help and index statistics, which lists what exactly is indexed. The Search page hyperlinked from the Navigation Bar and the Overview Frame.

Dense layouts: more information in less space

Our template technology (see FlexDoc/XML | Features) allows for fast programming of complex table-based grid layouts. 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: FlexDoc/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 are 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 DiagramKit 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.

DiagramKit is the default (native) diagramming engine of FlexDoc/XML. All diagrams on this page and in WSDLDoc examples have been generated by it.

The following screenshots show two diagrams of the same XSD component. On the left is the diagram with the element/attribute properties. On the right is the diagram without the properties. Click on the screenshots to see each diagram in full size within the corresponding documentation:

For more details, please see:

Table representation of complex content

This is another way to represent the complex content defined by an XSD component – the most complete and easy to understand. It consists of two tables like shown on the following screenshots:

Attributes

Content Element Model

Such Table Representations can also include the full or partial description of each attribute and content element. Thereby, they can be used as a light-weight compact documentation of those attributes and elements.

However, it does not work for all cases. If the complex content is defined within a local element itself (using an anonymous complex type), that cannot be documented only in such a way.
The Table Representation can be generated for the same component types as diagrams:

5. Possibility of unlimited customizations

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 greater 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 organized 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: {flexdoc-xml}/templates/WSDLDoc/css/azure-theme.css

How to specify it is shown in the HTML Option Inspector screenshot above. You should set:

  • Output | CSS | Generate named rules = all
  • Output | CSS | Generate named rules | Custom rules file = Stylesheet file path name

Note that the possibility to use any CSS stylesheets is available only under the “FlexDoc/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, FlexDoc 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, FlexDoc templates are more akin to XSLT scripts. For more details, please read: FlexDoc.XYZ | Overview.

Template Designer is covered by the separate “FlexDoc/XML SDK” license, which you need to acquire along with “FlexDoc/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 FlexDoc/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 FlexDoc/XML archive from the downloads page.
  2. Unpack it in some directory, e.g.:

    C:\flexdoc-xml

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

  3. Edit:

    {flexdoc-xml}/bin/generator.bat

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

    See also: FlexDoc/XML | Overview | Technical Requirements | Where to get Java / JavaFX?

  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: FlexDoc/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. 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 Linux

  1. Unpack the downloaded FlexDoc/XML archive at some location, which we shall designate as '{flexdoc-xml}'.
  2. Go to {flexdoc-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.

Running on macOS

  1. Unpack the downloaded FlexDoc/XML archive at some location (e.g. on Desktop), which we shall designate as '{flexdoc-xml}'.
  2. Go to {flexdoc-xml}/bin/macOS directory (open it with the Finder).

    The doc-generator (Template Processor) is launched by generator.command shell script file.

    Because of security control, all macOS shell script files found in the downloaded FlexDoc/XML archive cannot be executed straight. However, that is easy to overcome as described below for generator.command file:
    1. First, open generator.command with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. With that procedure, you will sign generator.command as its “owner/creator”, which is a precondition to be able running it.
    2. On top of that, you will need also to assign generator.command with the executable privilege. 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 at last, 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.

How to include XSD diagrams?

Diagrams are generated by a diagramming plugin.

Diagramming plugins are particular implementations of Element Image Provider. Since FlexDoc/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.

FlexDoc/XML currently includes a single diagramming plugin able to generate XSD diagrams: FlexDoc/XML DiagramKit.

DiagramKit is the native diagramming engine of FlexDoc/XML. It works synchronously with the Template Processor and generates beautiful XSD component diagrams (with the support of all possible hyperlinks), which are immediately inserted in the documentation output produced by WSDLDoc.

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

DiagramKit is implemented entirely in Java with the use of JavaFX. Unfortunately, since Java 11, JavaFX is not included in the standard Java SE and must to be either: The latter possibility is described below.

Once you have downloaded FlexDoc/XML archive and unpacked it at some location (which we shall designate as '{flexdoc-xml}'), do the following:

  1. Go to the downloads page once again and download from there (according to your OS):

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit”

    In case of Windows, you should get this archive:

    flexdoc-jre-17_windows.zip

    Unpack that archive into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}/jre

    That will be your Java to run FlexDoc/XML. You don't need to install anything else!
  2. Go to: {flexdoc-xml}/DiagramKit/

    Now, you can immediately run generator.bat and designer.bat found there to starts the Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

  3. Everything else is the same as described in How to run WSDLDoc.

See Also:

How to integrate with Ant/Maven?

A demo about that you can find in your FlexDoc/XML installation:
{flexdoc-xml}/integrations/ant/
{flexdoc-xml}/integrations/maven/
{flexdoc-xml}/DiagramKit/ant/
{flexdoc-xml}/DiagramKit/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 FlexDoc/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 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 “FlexDoc/XML” preselected in the «Product» field.

“FlexDoc/XML” 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 'flexdoc-xml.license' file, which you will receive by email.
The license file should be saved in FlexDoc/XML 'lib' directory (near 'flexdoc-xml.jar' file):

{flexdoc-xml}/lib/

where '{flexdoc-xml}' denotes your FlexDoc/XML installation directory.

See Also:

Full Licenses

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

License Description
FlexDoc/XML WSDLDoc Unlocks all functionality implemented in WSDLDoc templates. In particular, you will be able to:
FlexDoc/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).
FlexDoc/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:

Your goal The license(s) you need
  1. FlexDoc/XML WSDLDoc
  1. FlexDoc/XML WSDLDoc
  2. FlexDoc/XML DiagramKit
  1. FlexDoc/XML WSDLDoc
  2. FlexDoc/XML SDK
  1. FlexDoc/XML WSDLDoc
  2. FlexDoc/XML DiagramKit
  3. FlexDoc/XML SDK

You can order any combination of those licenses starting from Store page.