Clever Geek Handbook

＃マイクロサービスのドキュメント





元の記事は、マイクロサービスの世界でドキュメントが非常に必要とされる理由と、swaggerを使用してドキュメントを作成および公開する方法を反映しています。 順を追ったセットアップガイドではありません。









エントリー



数か月前、バックエンドのインターン開発者の1人が、新しいシンプルなサービスを開発するという仕事を得ました。 このサービスは、ユーザーアクティビティに関する電子メールレポートを生成することになっています。 タスクに複雑なものはなく、インターンは成功しました。 ただし、数週間後、特定のユーザーに関するより詳細な情報をレポートに含めたいと考えました。 このサービスを自分で更新することにしました。 「ユーザーサービスからデータを取得してメールに貼り付けるだけです」と私は考えました。



これを行うには数時間かかり、適切なRESTエンドポイントと必要な変更構造を見つけるために、他の2人の開発者を接続する必要さえありました。 「二度と。 これを行うには、より正確な方法が必要です...」、-ずっと私の頭の中で回転していました。

マイクロサービスアーキテクチャは、相互に通信する一連の独立したサービスを意味し、エンドユーザーにとっては単一のプログラムのように見えます。 マイクロサービス間のメッセージングで最も一般的なプロトコルの1つはRESTです。 問題は、REST自体が説明的なプロトコルではないことです。 これは、クライアントがURL、HTTPメソッド、および応答形式の特定の組み合わせを知っている必要があることを意味します。 場合によっては、リクエスト本文の形式を知る必要もあります。 通常、RESTインターフェースの実装は、組織で受け入れられている一般的な原則と伝統に基づいています。 いずれの場合でも、RESTエンドポイントは 、 他のすべての開発者がアクセスできる特定のドキュメントで常に説明する必要があります 。 それをどのように、どこに保存するかについては少し後で説明しますが、ここでは基本的なこと、つまりドキュメントの形式について説明します。







Sw歩









ドキュメントは、読みやすく 、書きやすく 、解析しやすく 、生成しやすく 、修正しやすく 、更新しやすいものでなければなりません。 ソリューションは、最も怠laな開発者でも使用できるほど単純でなければなりません。 少し調べた後、 Ataccamaで Swaggerを使用してREST APIを文書化することにしました。







Swaggerは、 ユーザーフレンドリーでコンピューターフレンドリーな形式（この場合はJSONまたはYAML）でREST APIを定義するためのフレームワークおよび仕様です。 しかし、Swaggerは単なる仕様ではありません。 その主な力は、追加のツールにあります 。 Swaggerには、（公式およびコミュニティで作成された）膨大な数の無料ユーティリティがあり、あなた（およびあなたの同僚）を少しでも幸せにすることができます。 これらすべてを自分のサーバーにインストールして、どのように機能するかを確認できます。たとえば、ドキュメントブラウザーやSwagger オンラインエディターを使用してみてください。







これをどうやってやるの？



Swaggerが素晴らしいと思う場合は、先に進んでください。 マイクロサービスの神秘的な世界であるAtaccamaでの使用方法について、詳細を説明します。







各マイクロサービスには、特定のフォルダーにSwagger記述のファイルがあり、すべてgitリポジトリーに直接保存されます。 説明は、Swaggerジェネレーターを使用して生成するか、手動で記述できます。 美点は、JSONおよびYAML形式を使用して定義を記述することです。 それらは簡単に解析でき、プロジェクトのアセンブリ中に、 RESTエンドポイントとドキュメントのコンプライアンスを自動的にチェックできます。 矛盾があると警告が生成されるため、開発者はドキュメントを最新の状態に保つことができます。







マイクロサービス内にドキュメントを保存すると、操作中にいつでもこのマイクロサービスから直接ドキュメントを表示できます。 これは、独自のマシンにサービスを展開するプロセスでRESTエンドポイントをテストおよびデバッグするのに役立ちます。 Swaggerには、RESTエンドポイントをテストするためのWebベースのツールもあります。







各マイクロサービスは独自のドキュメントを提供するため、プロジェクト全体の完全なドキュメントを生成するJenkins（またはその他のCIサーバー）に特別なタスクを設定できます。 このタスクは、すべてのマイクロサービスからSwaggerファイルを収集し、最小限の変更（重複排除、不要な属性の削除）を行い、プロジェクト全体の最新情報を含む単一のSwaggerファイルを生成します。







ドキュメントの公開。



集中ストレージとドキュメントの編集は、最初のステップにすぎません。 次に、社内のすべての開発者 、テスター、その他の関係者がアクセスできるようにします 。 Swagger UIはまさにこれに必要なものです。 Swagger UIは、小さなJavaScriptライブラリを使用して、すべてのRESTエンドポイントのHTML要素を生成します。これは、HTMLマークアップでさらに整理できます。











デフォルトでは、Swagger UIは独自のSwaggerファイルをサンプルとともにロードします。 他のすべてのAPIは手動でロードする必要があります。 ただし、構成には数秒しかかかりません。 







var swaggerUi = new SwaggerUi({ url: 'http://example.com/swagger.json', dom_id: 'swagger-ui-container' }); swaggerUi.load();


これで、生成されたドキュメントが読みやすい形式になりました。 サーバーに送信する時間。

少し前に、AtaccamaでDockerの使用を開始したので、 すべてのドキュメントを個別のdockerコンテナーにパックし、プライベートリポジトリーにアップロードしてから、クラスターをdockerにデプロイしてみませんか？ Jenkinsはこれをわずか数秒で実行できます。 その結果、ブラウザで表示できるドキュメントを常に更新しています。







さらに、Dockerを使用すると、さらにいくつかの利点があります。









そして、これはほんの始まりに過ぎません。



これは、RESTエンドポイントのドキュメントを生成し、マイクロサービスのdockerを使用して公開する方法の一般的なアイデアです。 残念なことに、マイクロサービスのこの迷路で文書化する必要があるのは同期RESTだけではありません。 ある時点で、より高度な通信システム、非同期メッセージング、キュー、イベントサブスクリプションなどに切り替えたいと思います。







Swaggerのto唱にもかかわらず、非同期メッセージを文書化する便利な方法はまだ見つかりませんでした。 実際、Attakkamでは、現在の決定に不満を抱いており、メッセージキューとその構造を記述するために、よりシンプルで美しいものを探しています。 これをもっとうまくやる方法についてアイデアがあれば、コメントに書いてください。 どんな面白いアイデアも歓迎します。







元の記事はこちらです。



投稿者Lubos Palisek

Ataccamaのバックエンドソフトウェア開発者。 新しいクラウドベースのテクノロジーとアイデアに貪欲です。



Ataccama Corporationは、データ品質管理、マスターデータ管理、エンタープライズデータ管理ソリューションを専門とする国際的なソフトウェア会社です。そのソリューションは、中規模企業から国際企業まで、250社以上で既に使用されています。さまざまな産業。

すべての質問や推奨事項を著者に喜んで翻訳します。







More articles:


All Articles