Auto-generate documentation

Sep 7, 2011 at 4:00 PM

First thing - a complement: RestCake is a nice piece of work.

This seems to be a function similar to the js generation, but the result should be a readable format.

Can this be done ?

Coordinator
Sep 10, 2011 at 9:52 PM

RestCake already generates documentation for a service, and it's quite extensive.  Go to your service route and append /_help at the end.  Let me know if that's what you're looking for. 

Sep 12, 2011 at 1:00 PM

This is the issuue I was looking for.

A few related ones:

  1. Can the _help expose also the non-primitive types involved (recursively) in the methods parameters ?
  2. Are the generated documentation and javascript proxy methods being cached (so they can be returned without going through reflection + formatting ? 
Coordinator
Sep 12, 2011 at 6:40 PM

1. The types of each parameter are shown in the "Signature" column of the table.  If you wish to see fully qualified type names (instead of just class names), there is a link at the top right of the table.  Also the "Returns" column shows the methods return type.  I'm not sure what you mean by recursive.  As in generics?  Like a List<Dictionary<string, Tuple<int, object>>>?  Types like that should be displayed correctly without a problem.

2. Yes and no.  The auto generated clients (for js and cs) are both cached, because they are more of a production concern (especially the js since it's likely being referenced from a production web ui).  The help page is really just for developers, and is not a production concern, so I didn't bother to cache it (though it would be trivial).  If you look in RestHttpHandler.cs (at the root of the main RestCake csproj), look at these methods:

returnClrClientDefinition()

returnJsClientDefinition()

returnHelpPage()

You'll see this in the beginning of returnJsClientDefinition()

string query = context.Request.Url.Query.ToLower();
if (s_jsProxies[type].ContainsKey(query))

{

context.Response.Write(s_jsProxies[type][query]);

return;

}

 

s_jsProxies is a static dictionary.  Static means that there will only ever be 1 instance of the dictionary per w3wp.exe process, so it's shared by all threads and requests in ASP.NET.