Dokumentacja usługi WCF

Question

Jaki jest najlepszy sposób udokumentowania/opublikowania informacji o usłudze WCF w dokumencie technicznym produktu, na który spojrzą zarówno programiści, jak i osoby niebędące programistami? Co jest najlepszym narzędziem do publikowania.

Answer 1

To w najlepszym razie drażliwa kwestia! :-)

Można wyeksportować opis usługi WCF w pliku WSDL i wzbogacić ją <xs:documentation> i <xs:annotation> elementów, a następnie przekonwertować do czytelnego dokumentu HTML przy użyciu transformacji XSLT - ale to jest mniej niż wielki i użyteczne, naprawdę ....

Oto link, który pokazuje, jak to zrobić: http://andrewtokeley.net/archive/2008/10/30/adding-wsdl-documentation-to-your-wcf-services.aspx

Kilka narzędzi XML tam również oferują sposoby udokumentowania plików WSDL - również często od tych dokumentacji i adnotacji tagi - jeden przykład jest tutaj: http://www.oxygenxml.com/doc/ug-oxygen/generate-wsdl-documentation.html

Oto wersja elektroniczna (i pobrania transformacja XSLT) do konwertowania dokumentacji i elementy adnotacji z Twojego WSDL: http://tomi.vanek.sk/index.php?page=wsdl-viewer

ja naprawdę nie mam ostateczną odpowiedź tutaj - ale zapalonym zainteresowanie tematem, także!

Marc

Answer 2

Spójrz na to pytanie: Best way to document a WCF interface.

Answer 3

Istnieje help page, który jest generowany podczas tworzenia usługi REST WCF przy użyciu WCF REST Starter Kit. Wydaje się, że nie używasz usługi REST, ale pomyślałem, że wspomnę o tym, ponieważ ten format może dobrze działać.

Korzysta z opisu operacji, aby odsłonić dane wejściowe atomu operacji.

Trochę refleksji okazało się to próba:

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(); 
}