メッセージバスAPIを文書化しますか？

Question

私は、私が取り組んでいるマイクロサービスアーキテクチャ用のAPIを文書化する何らかの方法で過去2〜3日を探してきました。 "メッセージ・ブローカー"としてX-パブ/ X-サブプロキシでNetMQを使用して、.NET 4.6.1

をC＃で書かれた

• ：まず、私はプロジェクトの非常に迅速な記述をあげます
• すべての通信は

それの短い私は他の人が文書化方法を知りたいということである他は、.NETアプリケーションであり、

一部のクライアントは、ブラウザでJavaScriptをされているプレーンなC＃のオブジェクトをJSONにシリアライズされますメッセージブに公開されているモデルs。私は、REST呼び出しを文書化するのに役立つかなりのプロジェクト（Swaggerなど）を見てきましたが、RESTを使用していません。私たちのアプリケーションは、ほとんどがJSONを使ったpub-subメッセージでイベントベースです。

私の最初の考えは、JSONスキーマを使ってJSONを文書化し、それをきれいにフォーマットされたAPIドキュメントに変換するツールを使用することでした。それはおそらくうまくいくでしょうが、気になるのは、ビルドプロセスの一環としてスキーマ生成を自動化するツールがないようです。私たちのモデルがAPIのドキュメントと異なる場合は、ビルドエラーであることを望みます。さらに、ビルドプロセスの一環として基本的なドキュメントを自動生成する方法があれば、ドキュメントを同期させることができます。

あなたはどうしていますか？メッセージバスアーキテクチャに固有の文書化ツールがRESTに欠けているため、メッセージキューに基づいたメッセージングアーキテクチャを使用するという私たちの決定に疑問を感じています。 :)

Answer 1

...スキーマ 生成を自動化するための任意のツールがあるように思えません...

ツーリングは地面の上に薄いことに合意しました。ただし、次のとおりです。https://github.com/NJsonSchema/NJsonSchema

あなたはどうしていますか？

興味深いことに、私はない10分前に同僚とこの正確な議論を持っていた：モデルは、事前に定義されたスキーマから逸脱した場合のp

は、我々はビルド（または受け入れテスト）の失敗が必要です。

したがって、NJsonSchemaパッケージを使用してモデルからスキーマを生成するステップをビルドに組み込むことができます。次に、出力されたスキーマをAPI docsスキーマと比較する比較ステップがあります。

逆に、スキーマからコードを生成し、その出力をビルド出力のモデルと比較することができます。

は...

... メッセージキューに基づくメッセージングアーキテクチャを使用するために我々の決定を疑問視もちろん、友人滞在。