Skip to content

Rough Book

random musings

Menu
  • About Me
  • Contact
  • Projects
    • bAdkOde
    • CherryBlossom
    • FXCalendar
    • Sulekha
Menu

Generating API Documentation from XML using XSLT

Posted on July 9, 2011July 9, 2011 by vivin

I work at Infusionsoft, and we offer our customers API access. Visibility and access to the various tables and their fields is controlled by an XML file on our end. Naturally, our customers require user-friendly documentation that tells them what tables and fields they can access and in what manner. Previously, a former developer had written a maven goal that would generate the API documentation from the XML file. Unfortunately this was something that he did on his own and the code wasn't in our subversion repository. When that developer left, we decided to take a look at the code to see if we could continue generating the documentation using the maven goal. We determined that the original solution though helpful, involved a lot of work in Java simply to generate API documentation. This was when I suggested using XSLT as it would be a remarkably lightweight solution and it is also perfectly suited to this task. My colleagues agreed and so I decided to go ahead with the task. There was one slight problem though. I had very little experience with XSLT! But how hard could it be? I love learning new things anyway!

As it turned out, it wasn't all that hard (this doesn't mean I am an expert; I'm still a novice!). I went through a few tutorials and examples and in about an hour or so I had a basic idea of the language (especially its functional aspect). It took me about a day to write out the entire XSLT document (tweaks and all). Most the time was spent looking up instructions in XSLT to do certain things (string operations, date formatting, etc.).

Here's an example of what I had to work with, from the XML document (this is not the exact document; it's just an example that follows the structure):

[sourcecode lang="xml"]




...


[/sourcecode]

As you can see, the structure is pretty simple. As far as the resulting API documentation was concerned, what I wanted was an index.html that contained links to other pages. These other pages should be structured so that there is an HTML page for each table. This page will contain information about the table fields, as well as their access modes (E: Edit, D: Delete, A: Add, R: Read). As it turns out, in XSLT 1.0, you cannot create separate documents. You can only transform one document into another document. In XSLT 2.0 however, you can transform one document into multiple documents using the xsl:result-document instruction.

The XSLT that I've written is pretty straightforward (if you know XSLT; even if you don't, you can kinda get the gist of it from the instructions). The only thing I had trouble with was translating the access-mode letters into their expanded forms. To do this, I had to write a recursive template that looks at each character (there are other ways). This is where the functional aspect of XSLT comes into play. Once I started thinking of XSLT like Lisp, it became much easier to write my solution because I wasn't fighting the language. Anyway, here is my solution:

[sourcecode lang="xslt"]




Edit
Delete
Add
Read
Unrecognized Access Mode:






Generated via XSLT on

Infusionsoft Table-Access Documentation

Database Tables & Fields










    Edit Delete Add Read






  • Generated via XSLT on

    <xsl:value-of select="@name" /> Table (Access Modes: <xsl:value-of select="substring($tableAccessModes, 1, string-length($tableAccessModes) - 1)" />)




    String












    even
    odd



    Field Name Type Access

    Back to list of tables








[/sourcecode]

That's all there is to it! To actually use the XSLT document to generate the API HTML files, I used Saxon, which supports XSLT 2.0. This is how I used it:

[sourcecode]
java -cp saxon9he.jar net.sf.saxon.Transform -t -s:api_field_access.xml -xsl:api_doc.xslt
[/sourcecode]

So if you're an Infusionsoft customer or a developer who is reading the API documentation, you now know how it was generated!

5 thoughts on “Generating API Documentation from XML using XSLT”

  1. Joey Novak says:
    July 10, 2011 at 11:12 am

    Hey Vivin,

    Is the latest on developers.infusionsoft.com from this method? I was using it the other day and ran into several fields that were reported as Strings instead of their proper types. Not sure if it was my code or yours.

    Here is what I sent Justing Gourley.

    I think there may be a mistake in the database documentation… It says that OrderItem Qty, PPU, and CPU are all Strings… I just got an error in my java sdk I wrote for a client that the Qty is actually coming from Infusionsoft as an Integer and not a string… It’s possible that this is a problem on my end, but I think Infusionsoft is returning it as an Integer instead of a string…

    I’m getting the same error on Contact.Validated

    The CPU and PPU fields appear to be Doubles
    And OrderITem.itemType, Integer instead of String

    The documentation is so helpful, I’m glad your maintaining it. Yeah, if I’d gotten permission to put it on a backlog, it would have been a lot cleaner.

    Reply
  2. vivin says:
    July 11, 2011 at 10:19 am

    Hey Joey,

    I made a few tweaks to the XSLT as I was writing this post. What I had before just duplicated what your Java code did. If a type is not specified in the field access XML file, it just assumes that it is a String. The only other option is to leave it blank. I will talk to Gourley about this to see what we can do (we might have to annotate everything in the field-access file).

    Another thing I noticed is that in the original code, table access-permissions were not inherited. So even if a table was marked “R”, the fields were listed as “EDAR”. I fixed this in the stylesheet.

    Update #1: In 22.10, the API documentation will be more accurate. I’ve defined a schema for the XML file using XSD and XML validation is part of the build process. This should take care of the type errors that you’re seeing.

    Update #2: As far as mavenizing the process, it’s irrelevant as to its impact on the consumers of our API. We didn’t mavenize the API-generation process since it doesn’t make sense to include the documentation itself in the code for the application.

    Reply
  3. michael says:
    July 26, 2011 at 2:35 am

    Out of curiosity do you code your xml by hand ie notepad or ms xml editor or do you use any commercuial xml editors? I am looking to purchase liquid xml editor (http://www.liquid-technologies.com/xml-editor.aspx) and would be interested in your feedback.

    Reply
  4. vivin says:
    July 27, 2011 at 10:55 am

    @michael
    I actually just write my code in vi 🙂 Sometimes I use IntelliJ when I’m at work. It does offer auto-complete and other such features. Then again, I don’t write XML on a regular basis and so vi is sufficient for me.

    Reply
  5. Peter says:
    September 21, 2011 at 3:03 pm

    This is pretty cool!

    Reply

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Meta

  • Log in
  • Entries feed
  • Comments feed
  • WordPress.org

Archives

  • February 2023
  • April 2020
  • February 2020
  • January 2020
  • December 2019
  • November 2019
  • September 2019
  • August 2019
  • July 2019
  • June 2019
  • May 2019
  • March 2019
  • February 2019
  • January 2019
  • December 2018
  • November 2018
  • September 2018
  • August 2018
  • July 2018
  • June 2018
  • May 2018
  • April 2018
  • March 2018
  • February 2018
  • January 2018
  • December 2017
  • November 2017
  • October 2017
  • June 2017
  • March 2017
  • November 2016
  • August 2016
  • July 2016
  • June 2016
  • February 2016
  • August 2015
  • July 2014
  • June 2014
  • March 2014
  • December 2013
  • November 2013
  • September 2013
  • July 2013
  • June 2013
  • March 2013
  • February 2013
  • January 2013
  • October 2012
  • July 2012
  • June 2012
  • January 2012
  • December 2011
  • November 2011
  • October 2011
  • September 2011
  • July 2011
  • June 2011
  • May 2011
  • February 2011
  • January 2011
  • December 2010
  • November 2010
  • October 2010
  • September 2010
  • July 2010
  • June 2010
  • May 2010
  • April 2010
  • March 2010
  • January 2010
  • December 2009
  • November 2009
  • October 2009
  • September 2009
  • August 2009
  • July 2009
  • May 2009
  • April 2009
  • March 2009
  • February 2009
  • January 2009
  • December 2008
  • November 2008
  • October 2008
  • August 2008
  • March 2008
  • February 2008
  • November 2007
  • July 2007
  • June 2007
  • May 2007
  • March 2007
  • December 2006
  • October 2006
  • September 2006
  • August 2006
  • June 2006
  • April 2006
  • March 2006
  • January 2006
  • December 2005
  • November 2005
  • October 2005
  • September 2005
  • August 2005
  • July 2005
  • June 2005
  • May 2005
  • April 2005
  • February 2005
  • October 2004
  • September 2004
  • August 2004
  • July 2004
  • June 2004
  • May 2004
  • April 2004
  • March 2004
  • February 2004
  • January 2004
  • December 2003
  • November 2003
  • October 2003
  • September 2003
  • July 2003
  • June 2003
  • May 2003
  • March 2003
  • February 2003
  • January 2003
  • December 2002
  • November 2002
  • October 2002
  • September 2002
  • August 2002
  • July 2002
  • June 2002
  • May 2002
  • April 2002
  • February 2002
  • September 2001
  • August 2001
  • April 2001
  • March 2001
  • February 2001
  • January 2001
  • December 2000
  • November 2000
  • October 2000
  • August 2000
  • July 2000
  • June 2000
  • May 2000
  • March 2000
  • January 2000
  • December 1999
  • November 1999
  • October 1999
  • September 1999
©2023 Rough Book | Built using WordPress and Responsive Blogily theme by Superb
All original content on these pages is fingerprinted and certified by Digiprove