How to document WCF web service in technical specification?

Question

Besides inserting WDSL into the technical specification, what are the recommended ways to document the WCF web service before starting coding?

Answer 1

We recently published a WCF-based SOAP interface for third-party integration. For each method, we presented the following:

• Method name
• Request example (dump format posting)
• Request Request Parameters
• Response example (transfer format dump)
• Request Request Parameters
• Cautions (gotchas)
• History

We also provide WSDL. You can use Microsoft Disco.exe for this. See also the related issue of obtaining WSDL .

Answer 2

Microsoft is documenting some WCF services on MSDN. I think you can get some ideas from the following links:

• Windows Communication Foundation Role Service Overview
  • RoleService
• Windows Communication Foundation Profile Service Overview
  • ProfileService
• Windows Communication Foundation Authentication Service Overview
  • AuthenticationService

Answer 3

Document the contract interface as you are documenting any other interface. Describe the operations, preconditions, post-conditions, reasons for the error, etc.

Answer 4

Also, if you are using a MessageContracts document, why are you using them ... believe me, you ask why you did this :)

Answer 5

• Describe service endpoints and available protocols / bindings. e.g. Https, RESTful?
• Security features, authentication, authorization and encryption.
• Explain options for using parameters in the operation contract.
• Hosting, IIS, WindowsService or console application.
• Service execution.