CODEWITHSUNDEEP
c#wcfweb-services
Loscas
Loscas

Reputation: 561

How to document a WCF web-service in a technical spec?

Other than pasting a WDSL in the tech spec, what are the recommended ways to document a WCF web-service before you begin coding?

Upvotes: 4

Views: 11097

Answers (4)

Thomas Bratt
Thomas Bratt

Reputation: 51812

We recently published a WCF based SOAP interface for third parties to integrate against. For each method we provided the following:

  • Method name
  • Request example (wire format dump)
  • Request parameters explanation
  • Response example (wire format dump)
  • Request parameters explanation
  • Caveats (gotchas)
  • History

We also provide the WSDL. You may want to use Microsoft's Disco.exe for doing this. See also a related question about obtaining the WSDL.

Upvotes: 6

Ray Lu
Ray Lu

Reputation: 26658

  • Describe service endpoints and available protocols/binding. e.g. Https, RESTful?
  • Security features, authentication, authorization and encryption.
  • Explain the use cases of parameters in operation contract.
  • Hosting, IIS, WindowsService or Console application.
  • Instancing of the service.

Upvotes: 1

sebagomez
sebagomez

Reputation: 9609

Also, in case you're using MessageContracts document why you are using them... trust me, you'll wonder why you did it :)

Upvotes: 1

Dave Dunkin
Dave Dunkin

Reputation: 1107

Document the contract interface as you would document any other interface. Describe the operations, pre-conditions, post-conditions, reasons for throwing a fault, etc.

Upvotes: 2

Related Questions