Documentación de servicio WCF

Question

¿Cuál es la mejor manera de documentar/publicar información en un servicio WCF en un documento de producto técnico que tanto los programadores como los no programadores verán? Además, ¿cuál es la mejor herramienta para publicar?

Answer 1

¡Eso es un problema espinoso en el mejor de los casos! :-)

Se puede exportar la descripción del servicio WCF para un archivo WSDL y enriquecerla con <xs:documentation> y <xs:annotation> elementos, y luego convertir eso a un documento HTML legible utilizando una transformación XSLT - pero eso es menos grande y útil, en realidad ....

Aquí hay un enlace que muestra cómo hacerlo: http://andrewtokeley.net/archive/2008/10/30/adding-wsdl-documentation-to-your-wcf-services.aspx

Varias de las herramientas XML por ahí también ofrecen formas de documentar archivos WSDL - a menudo también de esas etiquetas de documentación y anotación - un ejemplo está aquí: http://www.oxygenxml.com/doc/ug-oxygen/generate-wsdl-documentation.html

Aquí hay una versión en línea (y una transformación XSLT descargable) para convertir la documentación y elementos de anotación de su WSDL: http://tomi.vanek.sk/index.php?page=wsdl-viewer

realmente no tienen la última respuesta aquí - pero un gran interés en el tema, ¡también!

Marc

Answer 2

Tome un vistazo a esta pregunta: Best way to document a WCF interface.

Answer 3

Hay un help page que se genera cuando se crea un servicio WCF REST con el WCF REST Starter Kit. Parece que no estás utilizando REST, pero pensé que lo mencionaría porque este formato podría funcionar bien para ti.

Esto utiliza la Descripción de la operación para exponer una alimentación Atom de las operaciones.

Una pequeña reflexión nos salió esta muestra:

public Atom10FeedFormatter GetFeed(ContractDescription contractDescription) 
{ 
    List<SyndicationItem> items = new List<SyndicationItem>(); 
    foreach (OperationDescription od in contractDescription.Description.Operations) 
    { 
     WebGetAttribute get = od.Behaviors.Find<WebGetAttribute>(); 
     WebInvokeAttribute invoke = od.Behaviors.Find<WebInvokeAttribute>(); 
     string method = this.GetMethod(get, invoke); 
     string requestFormat = null; 
     if (invoke != null) 
     { 
      requestFormat = this.GetRequestFormat(invoke, od); 
     } 
     string responseFormat = this.GetResponseFormat(get, invoke, od); 
     string uriTemplate = this.GetUriTemplate(get, invoke, od); 
     WebMessageBodyStyle bodyStyle = this.GetBodyStyle(get, invoke); 
     string requestSchemaLink = null; 
     string responseSchemaLink = null; 
     string requestExampleLink = null; 
     string responseExampleLink = null; 
     if (bodyStyle == WebMessageBodyStyle.Bare) 
     { 
      UriTemplate responseSchemaTemplate = new UriTemplate("help/{operation}/response/schema"); 
      responseSchemaLink = responseSchemaTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
      UriTemplate responseExampleTemplate = new UriTemplate("help/{operation}/response/example"); 
      responseExampleLink = responseExampleTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
      if (invoke != null) 
      { 
       UriTemplate requestSchemaTemplate = new UriTemplate("help/{operation}/request/schema"); 
       requestSchemaLink = requestSchemaTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
       UriTemplate requestExampleTemplate = new UriTemplate("help/{operation}/request/example"); 
       requestExampleLink = requestExampleTemplate.BindByPosition(this.BaseUri, new string[] { od.Name }).AbsoluteUri; 
      } 
     } 
     uriTemplate = HttpUtility.HtmlEncode(string.Format("{0}/{1}", this.BaseUri.AbsoluteUri, uriTemplate)); 
     string xhtmlDescription = string.Format("<div xmlns=\"http://www.w3.org/1999/xhtml\"><table border=\"5\"><tr><td>UriTemplate</td><td>{0}</td></tr><tr><td>Method</td><td>{1}</td></tr>", uriTemplate, method); 
     if (!string.IsNullOrEmpty(requestFormat)) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Request Format</td><td>{0}</td></tr>", requestFormat); 
     } 
     if (requestSchemaLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Request Schema</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(requestSchemaLink)); 
     } 
     if (requestExampleLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Request Example</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(requestExampleLink)); 
     } 
     xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Response Format</td><td>{0}</td></tr>", responseFormat); 
     if (responseSchemaLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Response Schema</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(responseSchemaLink)); 
     } 
     if (responseExampleLink != null) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Response Example</td><td><a href=\"{0}\">{0}</a></td></tr>", HttpUtility.HtmlEncode(responseExampleLink)); 
     } 
     WebHelpAttribute help = od.Behaviors.Find<WebHelpAttribute>(); 
     if ((help != null) && !string.IsNullOrEmpty(help.Comment)) 
     { 
      xhtmlDescription = xhtmlDescription + string.Format("<tr><td>Description</td><td>{0}</td></tr>", help.Comment); 
     } 
     xhtmlDescription = xhtmlDescription + "</table></div>"; 
     var item = new SyndicationItem() { 
      Id = "http://tmpuri.org/" + od.Name, 
      Content = new TextSyndicationContent(xhtmlDescription, TextSyndicationContentKind.XHtml), 
      LastUpdatedTime = DateTime.UtcNow, 
      Title = new TextSyndicationContent(string.Format("{0}: {1}", this.Description.Name, od.Name)) 
     }; 
     items.Add(item); 
    } 
    SyndicationFeed feed = new SyndicationFeed() 
    { 
     Title = new TextSyndicationContent("Service help page"), 
     LastUpdatedTime = DateTime.UtcNow, 
     Items = items 
    }; 
    WebOperationContext.Current.OutgoingResponse.ContentType = "application/atom+xml"; 
    return feed.GetAtom10Formatter(); 
}