RE: Web API HelpPage

[Ian Thomas]

On a tangent, but might be of interest to some: DocPreview, in the VS Gallery – 
similar to Resharper's XML documentation preview (but free, though Resharper is 
not pricey of course and does much more).

http://bit.ly/1U4wbfn 

Developed by Oleg Shilo, relies on the source code (not the assemblies), 
supports C#/C++, in active development this month (v1.0.30). 

 

Related (sort of) is immoDoc.NET

https://github.com/marek-stoj/ImmDoc.NET 

which is (quoting) – 

a command-line utility for generating HTML documentation from a set of .NET 
assemblies and XML files created by the compiler. It's developed in C#.

• Simple

• Light-weight

• Blazingly fast 

  • 10-20 times faster than VsDocMan

  • 20-25 times faster than Sandcastle

• Supports .NET Framework 2.0 and above

• Can generate HTML and CHM documentation

• Uses Mono.Cecil

 

Ian Thomas

Albert Park, Victoria 3206 Australia

 

RE: Web API HelpPage

[Paul Glavich]

We started using the WebAPI help package quite some time ago. We did some 
tweaks, it came out with an update, we updated, broke pretty much everything. 
We have since customised the crap out of it and are now pretty happy with it. 
There are some shortcomings but overall it is doing what we want and dev story 
is pretty clean. We absolutely advocate some manual content that augment the 
pure tech stuff tho.

 

You can see the result here https://api.saasu.com

 

We have made the call a little while ago to not worry about any future 
upgrades, or anything like that. It has enough customisation to not warrant the 
pain of breakage.

 

-  Glav

 

From: ozdotnet-boun...@ozdotnet.com [mailto:ozdotnet-boun...@ozdotnet.com] On 
Behalf Of DotNet Dude
Sent: Wednesday, 9 March 2016 10:52 AM
To: ozDotNet <ozdotnet@ozdotnet.com>
Subject: Re: Web API HelpPage

 

 

On Wed, Mar 9, 2016 at 10:27 AM, Greg Keogh <gfke...@gmail.com 
<mailto:gfke...@gmail.com> > wrote:

Folks, just a heads-up ... I was looking for a way of auto-generating Web API 
documentation and I found THIS 
<http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages>
  from 2013, and there are similar articles all over the place, all a bit old. 
The advice on getting it going works after you add the Nuget package and make 
the tweaks. However: 

*   I had to manually alter the package code to read and merge multiple 
xmldoc files.
*   I cannot get the Request Formats to say anything but "Sample not 
available".
*   I cannot get the Additional Information column to display anything 
because my entity classes are in a portable library and can't have attributes 
applied to them.
*   All standard xmldoc tags in your comments are stripped back to empty 
strings in the web API help, meaning you can't have both API help and 
Sandcastle help for the same code with nice formatting and links.
*   Instructions on how to style the API help no longer work and it's all 
dull black and white.

 

So for simple API help it works, but the moment you want to customise or 
enhance anything it all goes to hell. I've wasted up to 4 solid hours trying to 
workaround all of the irritations I described. It's like someone had a great 
idea with this, but coded it like a high school project.

 

 

lol sound like every project I've inherited

 

Perhaps there are better tools, but a quick look at Swagger hints that you have 
to write almost all of the documentation and samples manually as JSON.

 

GK

 

Web API HelpPage

[Greg Keogh]

Folks, just a heads-up ... I was looking for a way of auto-generating Web
API documentation and I found THIS

from 2013, and there are similar articles all over the place, all a bit
old. The advice on getting it going works after you add the Nuget package
and make the tweaks. However:

   - I had to manually alter the package code to read and merge multiple
   xmldoc files.
   - I cannot get the Request Formats to say anything but "Sample not
   available".
   - I cannot get the Additional Information column to display anything
   because my entity classes are in a portable library and can't have
   attributes applied to them.
   - All standard xmldoc tags in your comments are stripped back to empty
   strings in the web API help, meaning you can't have both API help and
   Sandcastle help for the same code with nice formatting and links.
   - Instructions on how to style the API help no longer work and it's all
   dull black and white.


So for simple API help it works, but the moment you want to customise or
enhance anything it all goes to hell. I've wasted up to 4 solid hours
trying to workaround all of the irritations I described. It's like someone
had a great idea with this, but coded it like a high school project.

Perhaps there are better tools, but a quick look at Swagger hints that you
have to write almost all of the documentation and samples manually as JSON.

*GK*