www.flexdoc.xyz

• FlexDoc/XML
• WSDLDoc

FlexDoc/XML - WSDLDoc (WSDL/XSD Documentation Generator)

1. What is FlexDoc/XML WSDLDoc?
2. What you can generate with it
   • HTML Output
     • Framed HTML Documentation
     • Single-File HTML Documentation
   • RTF Output
     • RTF Documentation
     • PDF Documentation
3. What is processed/documented
   • Any number of input WSDL/XSD files
   • All referenced WSDL/XSD files
   • All interconnections between WSDL/XSD
   • Any XML schema design patterns
   • XHTML tags in your descriptions/annotations
   • Support of XML Catalogs
4. Documentation Features
   • Highly navigable framed HTML documentation
     • Detail header & navigation bar
     • Dynamic search functionality
   • Dense layouts: more information in less space
   • Abundance of cross-links
5. Documenting Web-Services & WSDL Definitions
   • Web-Service Documentation
   • WSDL Definition Documentation
6. Documenting XML Schemas & Data Types
   • Adding extensions to local element names
   • Unifying local elements by type
   • List of containing elements
   • Documenting of content model
     • Component Diagram
     • Table Representation
     • Simple Content Detail
7. Possibility of unlimited customizations
   • Template parameters
   • Generator options
   • Using custom CSS styles
   • Modifying templates with Template Designer
8. Getting Started
9. Licensing
   • Demo Mode
   • Trial License
   • Full Licenses
     • Which Licenses You Need - Use Cases

1. What is FlexDoc/XML WSDLDoc?

A powerful Web-Service/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.

WSDLDoc was derived from the early XSDDoc template set and inherits all its functionality. It includes two main templates:

• FramedDoc.tpl to generate framed HTML documentation
• SingleDoc.tpl to generate single-file HTML and RTF documentation

XSDDoc template set is found in 'WSDLDoc' subdirectory of FlexDoc/XML archive or installation: {flexdoc-xml}/WSDLDoc

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:

• Generation of file/page types:
  • Basic Content Pages
    • overview.html
    • namespace-overview.html
    • wsdl-overview.html, wsdl-source.html
    • schema-overview.html, schema-source.html
    • web-service.html, wsdl-service.html, wsdl-binding.html, wsdl-portType.html, wsdl-message.html
    • element.html, complexType.html, simpleType.html, group.html, attribute.html, attributeGroup.html
  • Cross-Reference Pages
    • components-summary.html
    • xmlns-bindings.html
    • index-all.html
    • index-files/index-n.html (index by letter)
  • Support Files
    • index.html
    • search.html
    • overview-frame.html
    • web-service-frame.html,
    • components-frame.html
    • namespace-frame.html
    • wsdl-frame.html
    • schema-frame.html
• Javadoc-like Navigation Bar
• Switching between FRAMES / NO FRAMES views

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:

• Main Sections (click on each link to see a corresponding screenshot):
  • Table Of Contents – the actual table of contents is generated by MS Word according to the special {TOC} field inserted in the RTF file and the headings of all sections (below)
  • Overview Summary
  • Namespace Overview – generated for each namespace
  • WSDL Definition Detail: Services, Bindings, Port Types, Messages
  • XSD Component Detail: Elements, Complex Types, Simple Types, Element Groups, Global Attributes, Attribute Groups
  • WSDL File Overview – generated for each WSDL file, may include also the full XML source of the file
  • Schema Overview – generated for each XML schema
  • XML Namespace Bindings – a reference table to quickly find which namespace prefixes are bound which namespace URIs according to the WSDL / schema sources (those prefixes also appear in the documentation as a part of each XML qualified name).
• 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

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.4 MB / 9.1 MB):

 

3. What is processed/documented

Any number of input WSDL/XSD files

• Including all XML schemas embedded in WSDL (within <wsdl:definitions>/<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.

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
• Unifying local elements by type

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 | Using HTML markup in annotations.

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

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: FlexDoc/XML | Documentation | Generator | Input XML | XML Catalogs

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

Detail header & navigation bar

Here is the screenshot of the header & navigation bar inserted at the top of each detail page. The navigation bar is added also at the bottom. The features highlighted with the text balloons are controlled by the corresponding template parameters as in the case of XSDDoc:

It is also possible to use the classical Javadoc-like navigation bar (which is controlled by the template parameter: Navigation | Detail Frame | Navigation Bar):

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 screenshots (click to enlarge).

You may think: What's special here? Just yet another pages of some documentation... But they use four grid layouts! If that technique was not applied, the information printed on those pages would occupy 3-4 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! 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

5. Documenting Web-Services & WSDL Definitions

Web-Service Documentation

Web-service is a notion introduced by WSDLDoc. It is based on the WSDL service definition. However, it moves away from the formal WSDL and rather describes the whole SOAP-based software service from the user/consumer point of view, bringing together all information related to that service collected across all other WSDL definitions and XSD components linked to it.

Each web-service is documented in a separate «Web-Service Documentation» page/block that includes:

• The web-service description.
• The details of all ports exposed by the web-service along with the summary of all methods available through each port.
• The details of all methods implemented by the web-service, including for each method:
  • The method description.
  • Its input, output and faults along with the type and structure of their content.

The screenshot on the left shows a Web-Service Documentation page. Click to view the HTML.

WSDL Definition Documentation

Such pages/blocks can be generated for each WSDL definition of the following types:

• services
• bindings
• portTypes
• messages

They provides all sorts of details about the given WSDL definition and its connections with everything else, as shown on the following screenshots (click to view the actual HTML):

6. Documenting XML Schemas & Data Types

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

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

Documenting of content model

The complex content (i.e. possible attributes and child elements) described by the component can be represented in different ways simultaneously:

• Diagram
• Table Representation

The simple content is fully documented as well with the Simple Content Detail.

Component Diagram

Component diagram can be generated for elements, complexTypes and element/attribute groups.

The diagram provides:

• A graphical view of the complex content represented by the component, including:
  • All relevant attribute declarations
  • The content element model, which represents all possible combinations of child elements. This includes also the depiction of all compositors (such as <xs:sequence>, <xs:choice>, <xs:all>) and all model groups involved in building of that content model.
• The members of substitution groups, whose head element appears in the content model or is the main component itself.
• Some information about ancestor components: element type, base type, element/attribute groups.
• The annotations to everything above
• The properties of elements and attributes, which provided extra information such as the element/attribute type, content, facets, default value etc. Properties are displayed in the little grid embedded within the diagram node depicting the element/attribute.
• Most of things depicted on the diagrams are hyperlinked to the corresponding documentation detail.

Component diagrams are generated by a diagramming plugins, of which there is currently one:

FlexDoc/XML DiagramKit

This is the native diagramming engine of FlexDoc/XML. It works synchronously with the Template Processor and generates beautiful XSD diagrams with the support of all features mentioned above along with all possible hyperlinks (including even from some properties). The diagrams are immediately inserted in the documentation output produced by WSDLDoc.

All diagrams visible on this page and in all WSDLDoc examples have been generated by DiagramKit.

The following screenshots are 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:

• How to include XSD diagrams?
• FlexDoc/XML | Features | Diagramming Plugins

Table Representation

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.

The Table Representation can be generated for the same component types as diagrams:

• Global & Local Elements
• Complex Types
• Element / Attribute Groups

Simple Content Detail

In XSD language, the simple content is defined with a simple type, which may include:

• XSD basic simple type
• Various restrictions specified with facets.
• The definition of a list
• The definition of a union (i.e. when several basic types or their lists may interchange)
• The default value

All of that is documented in the «Simple Content Detail» section (shown on the next screenshot) that consists of

• Simple Content Representation (visible at the top in the box), which briefly shows how the datatype is related to the XSD basic simple types, their lists or unions.
• The details of the union(s), list(s) and restrictions along with their descriptions found in the corresponding XML schema annotations.

7. 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. WSDLDoc is controlled by more than 700 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:

FlexDoc/XML | Documentation | Generator |

• Settings & GUI
• Template Parameters

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:

FlexDoc/XML | Documentation | Generator |

• Settings & GUI
• Output Formats

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

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:

• FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML
• FlexDoc/XML | WSDLDoc | Licensing | Full Licenses | FlexDoc/XML SDK

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.

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:

• FlexDoc/XML | Features | Template-driven architecture
• FlexDoc/XML | Documentation | Designing Templates | Running Template Designer
• FlexDoc/XML | WSDLDoc | Licensing | Full Licenses
• Licensing | Licensing of Templates | Custom Templates

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

This section was moved to FlexDoc/XML | WSDLDoc | How To Run. Please follow the links to jump directly to the corresponding content:

• Running on different systems
  • On Windows
  • On Linux
  • On macOS
• How to include XSD diagrams?
• How to integrate with Ant/Maven/Docker?

9. 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: Licensing | Demo License

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:

• All generated output documents will be specifically distorted by replacing some letters with shade ('░') characters (as well as contain special messages).
• XSD diagrams will contain trial watermark.
• Any output documents or diagrams may be used only for evaluation of this software. Any other usage is prohibited!
• Trial license is limited to 30 days.

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.

The license file should be saved in {flexdoc-xml}/lib/ directory (near 'flexdoc-xml.jar' file).

See Also:

• Licensing | Trial License
• Licensing | Licensing of Templates | Commercial Template Applications
• Licensing | Multiple Licenses

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: 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 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 FlexDoc/XML SDK license). Run any your custom templates derived from WSDLDoc.
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: Template Designer – you will be able to modify/create any FlexDoc/XML templates (including WSDLDoc templates, of course). The possibility to apply custom CSS styles. Please note that neither commercial template applications themselves (e.g. WSDLDoc) nor diagramming plugins are covered by this license!

See Also:

• Licensing | Full License
• Licensing | Multiple Licenses

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
WSDL/XSD documentation	FlexDoc/XML WSDLDoc
WSDL/XSD documentation XSD diagrams	FlexDoc/XML WSDLDoc FlexDoc/XML DiagramKit
Default WSDL/XSD documentation Custom WSDL/XSD documentation Custom CSS style sheet	FlexDoc/XML WSDLDoc FlexDoc/XML SDK
Default WSDL/XSD documentation Custom WSDL/XSD documentation Custom CSS style sheet XSD diagrams	FlexDoc/XML WSDLDoc FlexDoc/XML DiagramKit FlexDoc/XML SDK

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