Best way to document WCF interface? [closed]

Answer 1

I use two XSL files - one to document the WSDL for the operations, one to document the XSD for the data being passed around.

Unfortunately, so far, I haven't found a single cohesive solution, so I work with two XSLT files which transform the WSDL and the XSD respectively into HTML documentation.

WSDL Viewer does the job for the WSDL and produces a first HTML document, and xs3p does the same for the data contain in the XSD file.

Answer 2

I will put my interface contract into a common dll and hand that out. It gives them both the xml comments on the contract without giving the details of the service as well as allowing them to implement the service in an offline mode for testing until they're ready to use it. On top of that, they can bypass the wsdl and use ChannelFactory to create a channel.

Answer 3

Do use XML docs for that. There are a lot of smart meta-tags that will allow you to put code samples in them, references between operations, thrown exceptions etc.

Then you can use Sandcastle (+ some GUI you can find on Codeplex) to generate either chm, or html documentation.

Answer 4

Using the XML output from the compiler is nice...but it's been my experience that it's difficult to express the complete complexity of a service and it's expected invariants, dependencies, etc. in comments alone. You're better off maintaining a separate real document (Word, HTML, Wiki) to cover it all.

Answer 5

We use WCFExtras (http://www.codeplex.com/WCFExtras) for that.

Among other features it allows live exporting of your code xml comments into the generated WSDL, for example check how these xml comments:

    /// <summary>
    /// Retrieve the tickets information for the specified order
    /// </summary>
    /// <param name="orderId">Order ID</param>
    /// <returns>Tickets data</returns>
    [OperationContract]
    TicketsDto GetTickets(int orderId);

get reflected in the WSDL of that interface:

    <wsdl:operation name="GetTickets">
    <wsdl:documentation>
    <summary> Retrieve the tickets information for the specified order </summary> <param name="orderId">Order ID</param> <returns>Tickets data</returns>
    </wsdl:documentation>
    <wsdl:input wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_InputMessage"/>
    <wsdl:output wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_OutputMessage"/>
    </wsdl:operation>

An excerpt from their docs:

Adding WSDL Documentation from Source Code XML Comments This extension allows you to add WSDL documentation (annotaiton) directly from XML comments in your source file. These comments will be published as part of the WSDL and are available for WSDL tools that know how to take advantage of them (e.g. Apache Axis wsdl2java and others). Release 2.0 also includes a client side WSDL importer that will turn those WSDL comments to XML comments in the generated proxy code.