2

既存のWSDLファイルのドキュメントを作成する必要があり、ドキュメント内で作成したいと思います。問題は、wsdl：documentationがxml：langを属性として使用できるかどうか、またはドキュメントジェネレーターがそれを使用するかどうかについて何も見つからないことです。

これまでのところ、私はWebで何も見つけていません。また、二言語のドキュメントを作成したいのは私だけだとは信じられません。ヒントはありますか？

4

1 に答える 1

3

WSDL 1.1仕様から：

WSDLは、オプションのwsdl：document要素を人間が読める形式のドキュメントのコンテナとして使用します。要素のコンテンツは、任意のテキストと要素（XSDでは「混合」）です。ドキュメント要素は、任意のWSDL言語要素内で許可されます。

WSDL 2.0仕様から（私の強調）：

WSDL 2.0は、オプションのドキュメンテーション要素情報項目を、人間が読める形式または機械で処理可能なドキュメンテーションのコンテナーとして使用します。要素情報項目の内容は、任意の文字情報項目と要素情報項目（XMLスキーマ[XMLスキーマ：構造]の「混合」内容）です。ドキュメント要素情報項目は、WSDL2.0要素情報項目内で許可されます。

「 http://www.w3.org/ns/wsdl 」名前空間の他の要素情報アイテムと同様に、ドキュメント要素情報アイテムでは、[名前空間名]が「 http：//www.w3」ではない修飾属性情報アイテムを使用できます。 org / ns /wsdl "。xml：lang属性（[XML 1.0]を参照）は、ドキュメント要素情報項目のコンテンツで使用される言語を示すために使用される場合があります。

これはV1でどういうわけか忘れられ、V2で修正されたようです。基本的に、あなたはあなた自身です。

ただし、仕様でドキュメントにxml：langの使用が義務付けられている場合でも、クライアントが提供するWSDLを処理するためにクライアントが何を使用するかを知ることはできず、クライアントがドキュメントを適切に抽出できるかどうかもわかりません。

私がこれを言っても構わないと思いますが、あなたはこれに間違った方法でアプローチしていると思います。Webサービスのドキュメントは、WSDLに再開されません。はい、WSDLを提供することは、クライアントがWebサービスを呼び出すために必要な配管コードを簡単に生成できるようにするために必須ですが、それは呼び出しの技術を詳述するだけです。Webサービスの使用方法については何も述べていません。

YMMVですが、WSDLを超えて、次のことを行うことができます。

  • Webサービスの機能の概要から始めます。
  • それぞれの操作が何のためにいつ使用されるか。
  • パラメータの意味は何ですか、それぞれにどのような制約がありますか（たとえば、XSD制限で強化できないビジネス上の制約）。
  • Webサービスによって必要とされる/返される典型的なデータを含むいくつかのSOAPメッセージサンプル。
  • 予想されるエラー、エラーが発生するコード/説明、およびそれらのトラブルシューティング方法を説明します。
  • ビジネス上の制約を強調します（私は赤い太字のテキストを考えていますか？！）;
  • アーキテクチャ全体を説明する画像を挿入したい場合はどうなりますか？
  • などなど

これらすべての詳細をWSDLに追加することは制限されます。では、ドキュメントを、WSDLと、上記のような詳細を含む適切にフォーマットされた（言語固有の）PDFファイルで構成するのはどうでしょうか。

于 2012-12-08T19:52:52.363 に答える