Framework: .NET
Language: C#
Executable: WSDL Describer
Source Code (ZIP): WSDLDescriber.zip
Source Code (Github): samentries/WSDLDescriber

Introduction

This post is about a .NET application I developed called WSDL Describer. It is a desktop application based on another application I worked on while working in Elm. This application can read a WSDL XML, extract information from it, and summarize and organize the information on a word document.

In this post, I will mainly talk about my motivation on building this application and its implementation.

Motivation

I hate writing documentation. Spending hours, days, weeks or even months building a program, only to spend even more time writing about the program you just built is just dreadful. What’s even worse is that, the types of document being written are always the same: high level designs, unit test reports, integration guides, deployment instructions, and the list goes on. These repetitive documents are mind numbing and tedious. I don’t know any developer who likes writing them. And every time I open a word document and see this screen,
I die a little inside.

While working for Elm, I was building an array of web services that each were tailored either for private companies or government agencies. These web services are based on a product/service for Elm that I probably cannot call. Let’s just call it “Ninja Blade”. As you might expect, led me to writing the same documents after each life cycle of development for each released web service for Ninja Blade. This led to hours or days of constantly writing repetitive documents and pretty much resorting to just copying and pasting to save time, or at least give the illusion of saving time.

Luckily, an employee before me that worked on the web services for Ninja Blade made a program that saved time on writing one of its documents, which is the integration guide. Basically, the program analyzes some technology that factors in to building the signature web services Elm makes for their clients, and generates a PDF document that contains the integration guide of the web service that was built. It was so relieving to know that I never had to write an integration guide, thanks to this generator; it usually takes thirty pages to write this document, and could probably take a day or two to actually finish.

There were a few problems with using this generator, though.

Firstly, since the document is being printed on PDF, it is extremely difficult to re-adjust or correct the integration guide when needed. What’s even worse is that, when copying the contents to a Word document, the fonts, shapes and overall organization gets messed up. I tried finding a PDF to Word converter, but every time I find one, its either unbelievably expensive (
Seriously, I once found a converter for something like $150 to $200. Even a Wii U console now cost less than that), or they mess up the content of the document even more than copying and pasting. So, having only a PDF document alone turned out to be a pain.

Secondly, the generator is only specific to the web services of a certain product that Elm builds. This can’t write an integration guide for any other web service. So, if I worked on a web service not related to Ninja Blade, I have to manually write the integration guide from scratch, and I don’t want to go through that.

So, my boss and I decided to develop an application that can read WSDL XML files of web services built in Java, and generate custom made integration guide for the company. I took a program from one of my colleagues that can read WSDL XML files and extract their elements, and made the program to organize these elements and use these elements to write the company integration guide on MS Word.

After I built the program, it not only saved me time on writing integration guides for Ninja Blade web services, but also create guides for other web services as well. This also led me to making more programs that generate the other repetitive documents, such as the high level design and unit test report, reducing my work work time on documents from spending days on them to just a few minutes.

The though of not worrying about documentation is so relieving. I focused on my projects, improve my skills during my idle time, and haven’t worked on MS Word or Excel except for adjusting a few minor details. It was relieving.

Unfortunately, I was transferred to another project and team, and developing a different type of program, which led me to writing documents all over again.

Oh well. It was fun while it lasted.

So, because I know that someone out there is working on web services and they want to not spend time working on describing WSDLs or creating integration guides, I decided to share this program to the world. Unfortunately, I cannot share the source code and executable of the integration guide generator of WSDLs of the company since it belongs to the company. So, I decided to create another application that does a similar function and creating a generic document that basically describes a Java-based WSDL XML. I built the new application with algorithms and source code different from the last one, and describes the WSDL XMLs even better than the previous generator.

This application, however, has a few issues that may be solved in the future. Firstly, the application cannot describe web services generated from .NET, which I may tackle later in the future. And secondly, this application cannot describe all Java-based web services, since I need more samples to adjust the source code accordingly.

To tackle these issues, not only would I want to share this application, but make the source code open source as well. I hope that, by making it open source, the application would work a lot better and more beneficial towards others. Together, we don’t have to write documents describing WSDLs ever again.

Implementation

Other than the Main class, there are ten classes in the project:

• ApplicationManager
• MainUI
• WebMethodInfo
• WordWriter
• WsdlOperation
• WsdlPortType
• XSComplexType
• XSElement
• XSSchema
• XSSimpleType

Now before we get into the classes that controls the work flow of the application, I want to explain about the classes that is used to hold the element data within the WSDL. Let’s call them the “WSDL classes”.

The WSDL Classes

If you are unfamiliar on how WSDL is read and interpreted, please check out the tutorial here. It’s pretty useful.

Other than WebMethodInfo, the classes that are considered to be the WSDL classes are WsdlOperation, WsdlPortType, XSComplexType, XSElement, XSSchema and XSSimpleType. The names of the classes are based on the names of the XML element types in the WSDLs. For instance, XSElement represents , XSComplexType represents , and WsdlOperation represents , and so on. When reading the XML, the elements info are stored in these classes in order to interpret them when writing documents and filling in the WebMethodInfo object.

You might ask on why I didn’t write the document and fill the WebMethodInfo object while getting the info from the WSDL XML. Well, it is incredibly difficult and time consuming to do so, and would potentially increase the time complexity of the program, making it potentially slower.

MainUI Class

As the name of the class may suggest, this class is used to create and control the graphical user interface that the user will interact with and call the application manager. There are six windows application controls that the user will be concerned with:

• urlBox (Textbox): This text box is used to insert the URL of the WSDL XML to generate the description document from.
• authorNameBox (Textbox): This text box is used to insert the name of the author of the document (the user of WSDL Describer) in the generated document.
• statusBox (RichTextBox): This box will display the written status of generating the WSDL Description document. For example, if it is extracting info from the WSDL XML, it will display “Extracting WSDL information from XML”.
• generatorButton (Button): This button will call the save file dialog. If the user chooses the directory of where the newly created Word document will be stored and clicks the “Ok” button, the program will begin the process.
• saveFileDialog (SaveFileDialog): The dialog box will allow the user to choose the directory of where the newly created Word document will be stored.
• progressBar (ProgressBar): This bar will show how far along the process of generating the document is coming along. The longer the green area in the progress bar is, the closer it is to completing generating the document.

There is also one more control in the MainUI class that the user does not interact with, but it affects the other controls.

• timer (Timer): This control is used to update the status of generating documents. This is done by creating a new thread after choosing “OK” in the saveDialogBox to generate the document, and use the main thread to call the timer method in order to update the progressBar and statusBox.

ApplicationManager Class

This is the class that calls all of the methods crucial to the process of generating the WSDL Description document. There are three methods in this class, and one of which calls the other two methods:

• ExtractWSDLInfo: This method extracts information from the WSDL XML, and stores it in the WSDL classes mentioned above.
• FillInWebMethodInfo: This method takes the extracted information stored in the WSDL objects and use them to interpret the information and store the interpretation in the WebMethodInfo objects for each web method in the web service application
• DescribeWSDLInDocument: This is where all of the data flow to generate the document happens. It will call ExtractWSDLInfo, FillInWebMethodInfo, and the WriteDocument in the WordWriter class.

WordWriter Class

This is the class that will write the document. The main method of WordWriter that will be called in the ApplicationManager class is WriteDocument. However, many of the logic of the method is divided into manyh other methods in order to reduce the time complexity and organizing the section of the document.

The most important thing to notice in the class is the repeating lines of code crucial to writing the paragrtaphs. They are:

newParagraph = wordDoc.Content.Paragraphs.Add();

which creates a new paragraph, and:

newParagraph.Range.InsertParagraphAfter();

which ends the paragraph instantly.

The class is divided into nine methods:

• CreateCoverPage: This creates the cover page of the word document
• CreateIntroduction: This creates the introduction section of the document
• CreateListTemplate: This creates the list format in the document. So, this is where you can customize the way the list is organzined
• CreateXSD: This method creates the XML Schema Definition mini section in the Request and Response Message sections. This method will also call the CreateXSDString method to get the XSD string that defines the Request and Response Messages in the WSDL XML.
• CreateXSDString: This method will get the XSD string that defines the Request and Response Messages in the WSDL XML.
• CreateFieldDescription: This will create the tables that list the variable that are used as inputs and outputs. This method will also call the AddDataToFieldDecription to fill in the data and add rows in the tables
• AddDataToFieldDecription: This method will fill in the data in the Field Description tables. It will call itself recursively in order to add extra rows and data when necessary.
• CreateWSDLAppendix: This will write all of the raw WSDL XML string at the end of the document.
• WriteDocument: This is the main method that is used to write the document and call all of the mentioned methods above

Conclusion

This application, though it cannot analyze every kind of Soap web service, will help users who create web services for a living write documentation easier. It will also help the user analyze foreign web services that they did not work on.

I just wished that this application can generate WSDL description of every kind of web service, and not just Java APIs. I hope that making the application open and available in Github can help me reach that goal.

If there is anything missing from this post or unclear, please leave a comment, send me an email, or follow me on Twitter. I will reply as soon as I have the chance, and even update the post if I have to.

Try it

The source code and executable are available for download. You can contribute to the open source project in Github in order to improve the program for everyone. The links are mentioned above.

As for trying out the application, I will provide sample WSDL XMLs in order for you to test it out, as well as provide screenshots of their implementations and sample Soap requests to understand what the web services will contain, and compare them to the documents generated.

• TryWSDLDescriber1. Click here for the WSDL XML.
1. Sample Request and Response




2. Main Class of Web Service

• TryWSDLDescriber2. Click here for the WSDL XML.
1. Sample Request and Response




2. Main Class of Web Service

• TryWSDLDescriber3. Click here for the WSDL XML.
1. Sample Request and Response




2. Main Class of Web Service