How do I create documentation for my web service API?

Question

I am browsing my API through a web service ( .asmx ). Currently, only the default WSDL man page is available. Although it is very useful, it is not enough if my target audience requires a little more hands. For example, let's say I want to give some examples, but you still need to automatically create method signatures, etc.

Are there any good semi-automatic (automatic method signatures, but can still provide examples) to achieve this? I am looking for something like this that can also be serviced. Ideally, something that would help me change the default WSDL (I really like this page) would be great. All I need is documentation that will be automatically available with the service when it is deployed.

Any suggestions?

Answer 1

Perhaps the easiest way is to use comments on the XML documentation.

XML documentation comments

Using these comments, you can automatically generate HTML documentation. For example, using Sandcastle or NDoc3

Creating Sandcastle documentation when creating a Visual Studio project

And in the end, you can automatically save the html documentation in a shared location near your service, and it can be easily moved there using a browser. Thus, everything can be documents close to wsdl + html

Answer 2

This is pretty easy. If you decorate all your classes and methods with triple /// comments, then you can create documentation. See here:

http://msdn.microsoft.com/en-us/library/dd233217.aspx

http://www.developerfusion.com/article/84436/documentation-made-easy-with-c-and-xml/

Answer 3

Agree with the other posters, however I have used NDoc3 with great success. This is pretty fast than Sandcastle (which is also a very good tool). NDoc3 will generate .chm, .doc, and .html output.

NDoc3 and Sandcastle generate documentation in MSDN format.

NDoc3 - http://sourceforge.net/projects/ndoc3/