how to document web services

Explain how to document web services.

ASP.NET web services are considered as self documenting as they provides all information about what methods are available and what parameters they require using XML based standard called WSDL. We can also provide addition information about the web services using their WebService and WebMethod attributes.

You can add descriptions to each method through the Description property of the WebMethod attribute and to the entire web service as a whole using the Description property of the WebService attribute. You can also apply a descriptive name to the web service using the Name property of the WebService attribute. The attributes have name, description and namespace as properties which are shown in following example:

[WebService(Name = "Customer Service", Description = "Retrieve the Customer details",Namespace=http://www.apress.com/ProASP.NET/)]
public class Customer : System.Web.Services.WebService
{
     [WebMethod(Description = "Returns Customer Count")]
     public int GetCustomerCount()
     { ... }

     [WebMethod(Description = "Returns the list of Customer")]
     public DataSet GetCustomer()
     { ... }
}

Namespace allows your web service to be uniquely identified. By default, ASP.NET web services use the default XML namespace http://tempuri.org/, which is suitable only for testing. XML namespace simply identifies your web service. XML namespaces usually look like URLs. However, they don't need to correspond to a valid Internet location.