1

Manual REST documentation through Document! X?

Michael Mortensen

23 November 2012 09:25

Completed

Follow

Hi there,

For our company i need to do normal technical documentation of a .NET SDK which is supported out of the box in your fine product.
However, I also need to document the REST API that the SDK uses; for this task I would like to ask what (with the current 2012 version of Document! X and HelpStudio), would be the easiest way to manually create a website a bit like these:

http://msdn.microsoft.com/en-us/library/windowsazure/dd135733.aspx
http://docs.amazonwebservices.com/AmazonS3/latest/API/RESTServiceGET.html
https://developers.google.com/custom-search/v1/using_rest

Personally I lik the Amazon documentation best, but I favor MSDN styled website any day, so a possible solution that takes the best from the two worlds would be appreciated.

Thanks in advance - and do keep up the good work.

• Facebook
• Twitter
• LinkedIn

11 comments

• 0
  
  Richard Sloggett 26 November 2012 11:20

  At present you would need to author the REST documentation manually I'm afraid. The 2012 style templates will give you an overall style similar to MSDN, but the actual content you would need to structure yourself.

  You can use Example Code widgets for example / syntax portions and you could certainly create some widgets for the repeating sections - i.e. create widgets for the "Requests", "Responses" and "Examples" sections with parameters for each sections that you want to be editable. That would reduce to a minimum the amount of duplication. Let me know if you have any problems getting up and running with some custom widgets for this.

  REST documentation support is top of the backlog for our 2013.1 release so I'm hopeful you will see something that will ease the pain before too long.

• 0
  
  Michael Mortensen 10 December 2012 12:07

  Hi Richard,

  Thank you for your response.
  
  I think my main focus for the rest of 2012 will be documentation of our SDK and then focus on REST documentation with your (hopefully soon-to-be-released) 2013.1 release (i guess .1 means Q1?).

  Keep up the good work.

• 0
  
  Michael Mortensen 25 January 2013 06:13

  Hi Richard,

  Do you have a conservative estimate on the ETA for REST documentation?
  Thanks.

  Kind regards,

  Michael 

• 0
  
  Richard Sloggett 25 January 2013 09:25

  Don't have a date as yet, but I can tell you that work is underway and is progressing well. I will keep you posted as soon as we have more news.

  One thing we are curious about - do you currently create a WADL or some other definition for your REST services? What technology are you using to code your services (e.g. Java, MVC etc.).

• 0
  
  Michael Mortensen 25 January 2013 10:04

  Hi Richard,

  Sounds great.

  For the REST service we are using Microsoft ASP.NET/WCF with a generic Stream as return value.

  The reason for the Stream is, that it gives us the flexibility to return whatever value we like, while maintaining 100% control of the HTTP headers, compression and so forth; if the client ask for its, it will be served :-)
  
   We follow - to some extend - the best practises from the books "REST in Practice", "RESTful Web Services Cookbook" and the powerpoint here: http://www.slideshare.net/kjbuckley/doing-rest-right-3385800

  All REST method are decorated with an OperationContractAttribute and either WebGetAttribute or WebInvokeAttribute.

  Hope this helps.

• 0
  
  Richard Sloggett 29 January 2013 13:32

  For operations, your WCF services will be capable of publishing WSDL metadata - that will set you up nicely to use the Document! X web service documentation. I'm not sure if WebGet operations will be including the generated WSDL, but we will be including a couple of other options to specify pure http operations.

• 0
  
  Michael Mortensen 29 January 2013 13:44

  You can see an example here: http://api.ofir.dk/Security/Policies/help
  
  Here i would love if i could just "customize" the documentation as stated earlier in this entry.
  That means Document! X can either have a template for REST based services which I can fill manually and/or Document! X can do the hard work parsing the classes decorated with  the OperationContractAttribute and then let me edit/add accordingly so I may end up with something from the best of the Amazon documentation styled the MSDN way.
  
  Anyway .. that is my wish .. either way I look forward to try the new REST/Service documentation :-) 

• 0
  
  Richard Sloggett 29 January 2013 13:52

  Thanks for the info. I think you may need to add a:

  <serviceMetadata httpGetEnabled="true" />

  entry to your service configuration in order to have it provide a wsdl file - if that was enabled then http://api.ofir.dk/Security/Policies/?wsdl would return a WSDL definition of your services that Document! X could then use to document them.

  Your description of Web Service documentation is what we are shooting for - a modern, crisp design with as much information about the services as possible automatically populated, but with the ability to use Content Files to provide textual descriptions / examples etc - in the same way as for .NET. It will be a "first class citizen" in Document! X - so the link designer, link check/spell check/find and replace tools, autodoc etc. will all work as you would expect them to.

• 0
  
  Michael Mortensen 29 January 2013 14:07

  What you refer to look a lot like the SOAP protocol where a WSDL is possible; however for a REST based webservice, WCF have no knowledge on how to generate this (at least to my knowledge and way of implementing the REST).

  Our web.config looks like this in regards to the service model:

  <system.serviceModel>
  <serviceHostingEnvironment multipleSiteBindingsEnabled="true" />
  <standardEndpoints>
  <webHttpEndpoint>
  <standardEndpoint name="" helpEnabled="true" automaticFormatSelectionEnabled="false" contentTypeMapper="ContentTypeMapper" />
  </webHttpEndpoint>
  </standardEndpoints>
  </system.serviceModel>

  Developers on stackoverflow tend to agree: http://stackoverflow.com/questions/6030749/wsdl-for-rest-wcf

  Anyway, if a manual documentation is possible I will still be a happy camper although it is a little extra work in comparison to lay out the groundwork as you support now by WDSL.

• 0
  
  Richard Sloggett 06 February 2013 09:26

  Would you be interested in getting early access to a pre-release build that contained the REST documentation functionality? We would very much like to get early feedback on this new functionality earlier rather than later. We would also like to start a dialog with you about how you are developing your web services with a view to simplifying / clarifying the process of getting the definition file necessary to drive the Document! X documentation.

  Drop me an email direct (richard(at)innovasys.com) if you would like to get involved. If anyone else is reading this thread and would also like to get involved  in helping shape the final functionality for our WSDL/REST service documentation feel free to drop me an email also.

• 0
  
  Richard Sloggett 23 May 2013 10:30

  Just an update for anyone reading this - we have now implemented full support for REST and SOAP web service documentation in our 2013.1 release. Many thanks to Michael for this suggestion.