OpenMRS プロジェクト

このページには、Google シーズンの Google ドキュメントで承認されたテクニカル ライティング プロジェクトの詳細が記載されています。

プロジェクトの概要

オープンソースの組織:
OpenMRS
テクニカル ライター:
ソーラブ
プロジェクト名:
REST API 用のユーザー フレンドリーな GitHub ドキュメントの拡張
プロジェクトの期間:
標準の長さ（3 か月）

プロジェクトの説明

主要目標

OpenMRS Swagger ベースの REST API ドキュメントを拡張し、API の使用に関するガイダンスを追加しました。

プロジェクトの説明

OpenMRS REST API は、デベロッパーが OpenMRS からデータにアクセスするための重要なメカニズムの一つです。OpenMRS Webservices API については、Swagger ベースで自動生成されたドキュメントと、静的な GitHub ベースのドキュメントがすでにあります。このシーズンの Google では、この GitHub ベースのドキュメントを拡張する予定です。

概要

Burke が指摘するように OpenMRS Talk について少し調べた結果、このプロジェクトは 2017 年に GSOC プロジェクトとして始まったことがわかりました。Gayan Weerakutti では、OpenMRS REST API の既存のドキュメントを改善することを主な目的として、Swagger 仕様を改善し、Swagger 仕様の生成方法を改善して、より優れたバージョンの swagger ドキュメントを生成します。この OpenMRS のトーク記事には、このプロジェクトで達成された関連するすべての詳細情報が要約されており、非常に有用でした。

その後、2019 年にこのプロジェクトを刷新し、Swagger のドキュメントの微調整から移行し、これにバリエーションを持たせました。そこで、GitHub に対応した静的なドキュメントを作成しました。ドキュメントの今シーズンにも拡張する予定です。

現在のプロジェクト提案の概要は次のとおりです。

  1. 一般的な言語（特に Java と JavaScript）で例を挙げる。
  2. Swagger の「try-out」機能と同様に、スレートのドキュメント用にプレイグラウンド サポートを追加します。
  3. これまでに行った作業をリファクタリングし、改善する。
  4. 不足しているリソースを見つけて追加する。
  5. ドキュメントのコンソール セクションに詳しい説明を追加します。

詳細な説明

  1. さまざまな言語で例を挙げてもらいます。

Java で SDK ベースの例を追加し、レトロフィットのサンプルを追加することをおすすめします。レトロフィットの例を追加すれば、JavaScript のような別の言語でサンプルを追加しても、レトロフィットのサンプルを追加するほど役に立ちません。OpenMRS Android クライアントの操作中にこれらの REST API を使用していたため、Android 用のエンドポイントを使用するためにサポートが必要なときはいつでも参照できるリソースがありませんでした。また、Android クライアントの OpenMRS API エンドポイントをいじった経験があるので、質の高いサンプルを作成することができるでしょう。 メンターと話し合い、決定事項に取り組みます。 また、サポートされている操作の例を追加するだけでなく、一部のプログラミング言語の OpenMRS サーバーで認証する例も追加する必要があります。現時点では、そのための curl の例しかありません。

  1. API のサンプルをテストするための Playground のサポートを追加する

私はこの機能を、デモサーバーでホストされている OpenMRS の Swagger ドキュメントで使用しましたが、あらゆる API ドキュメントに含めると実に便利なツールです。 ここで少し調べたのですが、Swagger-UI 仕様を現在の静的ドキュメントに埋め込むのはそれほど難しくありません。表示と非表示の切り替えを使用し、現在の swagger ドキュメント コードを使用します。 このようにして、試用機能が現在の API 仕様で引き続き動作していることを確認できます。これは、現在の静的ドキュメントにプレイグラウンド機能を統合できる方法の一つだと考えています。

  1. これまでに行った作業をリファクタリングして改善する
現在の curl の例を確認する

このセクションは、今年このプロジェクトで重点を置いたものです。現在、GitHub API ドキュメントには curl の例のみが記載されており、その一部はデモサーバーで直接実行してブラウザから直接確認することはできません。現在のすべてのエンドポイントをテストし、curl リクエスト実行時に得られるさまざまな curl サンプルのレスポンスを含むシンプルなドキュメントを維持します。必要に応じて、Swagger ドキュメントに組み込まれた try-out 機能に加えて、Postman を使用してこのタスクを行います。

一部の例で API レスポンスがない

現在の curl の例にはレスポンスが追加されていますが、一部の curl の例にはレスポンスがありません。リソースのパージなどのオペレーションでよくあるレスポンスが冗長でなくても、考えられるすべてのレスポンス コードとそれを取得する理由を文書化しましたが、これにより、API ドキュメント全体で例がより統一されると思います。

さまざまなオペレーションで実用的な例がない

これは、API ドキュメントで以前に達成した作業をリファクタリングするうえで最も重要な部分です。ドキュメントには、cURL で直接実行できる具体的な例がありますが、いくつかはやや抽象的な内容であるため、経験豊富なデベロッパーにとっては参考になりますが、初心者にとっては煩わしさが残ります。 OpenMRS の講演のこの投稿から、優れた例は貴重ではないことがわかります。したがって、作業例を追加する以外に、構文のハイライト表示もサポートできます。これは、slate がバンドルされているため、ここで学んだように、非常に簡単です。

burke がこの投稿で何度も強調したように、優れた UI と魅力的なインターフェースの代わりに、ドキュメントのシンプルさと説明性を好むため、私はこれらの原則に従い、現在 OpenMRS Webservices API に取り組んでいるデベロッパーとコミュニティとの関わりをして、以前に文書化されたエンドポイントをできる限りわかりやすいものにしようとします。私のフォーム リソースの属性タイプの説明を収集するためのトーク投稿で行ったように、ここで PR に明確になっていませんでした。私はメンターと話し合い、ドキュメントに本当に価値をもたらし、最初に達成すべきことは何かを判断し、優先順位を付けて取り組みます。

ユースケースを見出しとして明示

私は、コツをつかむためだけに多くの API ドキュメントを見てきました。そのすべてにユースケースが明確な見出しとして記載されていますが、明示的に表示されていないユースケースもあります。これらはリソースとサブリソースの定義の後に続く定義と例の中に融合されています。 デベロッパーがユースケースを検索しなくても使用できるように、ドキュメント内でユースケースを個別のエンティティとして分離する努力が必要だと思います。

  1. 不足しているリソースを見つけて文書化する

    現在のプロジェクト状態にはここにリソースが記載されていますが、こちらの Swagger ドキュメントの最新バージョンを見ると、GitHub に適した API ドキュメントの現在のリソース スイートに追加できる多くのリソースを理解できました。ドキュメントには、2019 年のドキュメントのシーズン中に他のリソースで達成した説明も記載されています。 ドキュメントに追加する必要があるトピックについて説明し、適宜追加します。

結論

私はここしばらく OpenMRS コミュニティに参加しています。私は Android クライアント プロジェクトに積極的に貢献しており、API を頻繁に操作してサーバーと通信しています。したがって、自分自身で開発者として自分の作業を確認し、他の開発者の作業を容易にするかどうかを評価できるため、API ドキュメントを拡張するこのプロジェクトにかなり取り組むことができると感じています。ここにホストされているユーザー フレンドリーなドキュメント リポジトリに使用されているツールに慣れたため、ReM のドキュメントやツールに慣れるために、ReM のドキュメントを少し改善するために、API ドキュメントを改善します。

週に 1 回、トークの投稿で進捗状況をお伝えします。これにより、コミュニティからフィードバックを得ることができ、メンターやコミュニティと密接に連携しながら、この期間のドキュメントを最大限に活用できます。