2009-05-05 14 views
22

私はWCFを使用しており、社内のアプリケーションのために他の会社に提供するインタフェースとサービスを文書化したいと考えています。これらのインタフェースを文書化する最良の方法は何ですか?私は、コードとインラインでドキュメントを持っていることを好むだろうし、HTMLを出力するために何かを持っているが、それを行うための推奨された方法があるか分からない。WCFインターフェイスを文書化する最も良い方法は?

答えて

5

XMLドキュメントを使用してください。コードサンプルを入れたり、操作間の参照、例外を投げたりするスマートなメタタグがたくさんあります。

次に、Sandcastle(Codeplexで見つけることができるGUI)を使用して、 chm、またはhtmlのドキュメントを参照してください。

+0

WCFExtrasの実装は優れた選択肢です。 – TylerY86

+0

[elaboration] XML文書を直接記述子に結びつけます。 XMLドキュメントを使用するのが適切ですが、SandcastleまたはSHFBはスタンドアロンのドキュメントには絶対的に適していますが、WCFExtrasと同様のサードパーティですが、シナリオは限定されていません。 – TylerY86

0

コンパイラからのXML出力を使用するといいです...しかし、それだけでは、サービスの完全な複雑さを表現するのは難しいですし、不変量、依存性などはコメントだけでは予測できません。別の実際の文書(Word、HTML、Wiki)を維持して、それをすべてカバーする方がよいでしょう。

3

2つのXSLファイルを使用します.1つは操作用にWSDLを文書化し、もう1つは渡されるデータ用にXSDを文書化します。

残念ながら、これまでのところ、単一の結束ソリューションは見つかっていないため、WSDLとXSDをそれぞれHTMLドキュメントに変換する2つのXSLTファイルを使用しています。

WSDL Viewer WSDLのジョブを実行し、最初のHTML文書を生成し、xs3pは、XSDファイルに含まれるデータに対して同じ処理を行います。

0

私は、共通のdllに私のインタフェースコントラクトを入れ、それを渡します。これは、サービスの詳細を提供することなく、契約のxmlコメントを提供するだけでなく、サービスをオフラインモードで実装して、使用準備が整うまでテストすることを可能にします。さらに、wsdlをバイパスしてChannelFactoryを使用してチャネルを作成することもできます。

36

私たちはWCFExtras(http://www.codeplex.com/WCFExtras)を使用しています。

<wsdl:operation name="GetTickets"> 
    <wsdl:documentation> 
    <summary> Retrieve the tickets information for the specified order </summary> <param name="orderId">Order ID</param> <returns>Tickets data</returns> 
    </wsdl:documentation> 
    <wsdl:input wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_InputMessage"/> 
    <wsdl:output wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_OutputMessage"/> 
    </wsdl:operation> 

/// <summary> 
    /// Retrieve the tickets information for the specified order 
    /// </summary> 
    /// <param name="orderId">Order ID</param> 
    /// <returns>Tickets data</returns> 
    [OperationContract] 
    TicketsDto GetTickets(int orderId); 

そのインターフェイスのWSDLに反映されます。他の機能の中で

は、それは例えば、これらのXMLコメントがどのように確認し、生成されたWSDLにあなたのコードのXMLコメントのライブエクスポートすることができます

docsからの抜粋:

ソースコードからのWSDLドキュメントの追加コメント この拡張子では、ソースファイルのXMLコメントからWSDLドキュメント(annotation)を直接追加することができます。これらのコメントは、WSDLの一部として公開され、WSDLツール(たとえばApache Axis wsdl2javaなど)を活用する方法を理解しているツールで利用できます。リリース2.0には、生成されたプロキシコード内のWSDLコメントをXMLコメントに変換するクライアント側WSDLインポータも含まれています。

+2

IDEにも表示されますか? Visual StudioのIntellisenseのように? – Farinha

+2

誰かがこれを見つけた場合、最新のものは[ここ](https://wcfextrasplus.codeplex.com)です。[nuget](https://www.nuget.org/packages/WCFExtrasPlus/2.4.0)も同様にダウンロードできます。 – Joyce

+0

すぐわかりませんが、上記のコメントは、WCFExtras +を別のプロジェクトとして参照していますが、WCFExtrasの作業の続きです。いい物。 – TylerY86

関連する問題