OpenMRS プロジェクト

このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。

プロジェクトの概要

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

プロジェクトの説明

主要目標

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

プロジェクトの説明

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

概要

Burke の提案に従って OpenMRS Talk について少し調べたところ、このプロジェクトは 2017 年に GSOC プロジェクトとして開始されたことがわかりました。Gayan Weerakutti 氏は、OpenMRS REST API の既存のドキュメントを改善することを主な目的としていました。Swagger 仕様を改善し、Swagger 仕様の生成方法を改善することで、Swagger ドキュメント自体のバージョンを改善しました。プロジェクトで得られたすべての関連情報は、この OpenMRS トーク投稿に要約されており、非常に有用でした。

その後 2019 年にこのプロジェクトが刷新され、Swagger ドキュメントの微調整から移行し、さまざまなバリエーションを生成しました。代わりに、GitHub でわかりやすい静的ドキュメントを用意し、今シーズンの Google ドキュメントに拡張する予定です。

現在のプロジェクトの提案について簡単に説明します。

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

詳細な説明

  1. さまざまな言語で例を挙げます。

SDK ベースの Java にサンプルを追加し、ドキュメントをさらに充実させるレトロフィット サンプルをおすすめします。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 サンプルのレスポンスを含むシンプルなドキュメントを維持します。このタスクを実行するには、必要に応じて、Postman と swagger ドキュメントに組み込まれているトライアル機能を使用します。

一部の例に API レスポンスが含まれていない

現在の curl の例にはレスポンスが追加されていますが、一部の curl の例にはレスポンスがありません。リソースのパージなどのオペレーションでは通常レスポンスが冗長でない場合でも、JSON API レスポンスの例を用意すべきだと思います。ただし、考えられるすべてのレスポンス コードと、それらを取得する理由を記載しています。これにより、API ドキュメント全体のサンプルがより統一されると思います。

さまざまなオペレーションの実例がない

これは、API ドキュメントで以前に完了した作業をリファクタリングする際の最も重要な部分になると思います。ドキュメントには、cURL で直接実行できる具体的な例が記載されていますが、その中には、経験豊富なデベロッパーには参考になるものの、新規デベロッパーにはわかりにくいものもあります。OpenMRS トークのこの投稿から、良い例は貴重なものであることがわかりました。そのため、作業例を追加する以外にも、構文ハイライトをサポートできます。これはそれほど手間がかからず、Slate にバンドルされているため、ここで確認したように簡単に行うことができます。

burke が投稿で何度も強調しているように、優れた UI や洗練されたインターフェースよりも、ドキュメントの簡潔さと説明性を重視しています。この原則に従い、以前にドキュメント化されたエンドポイントを、OpenMRS Webservices API で現在作業しているデベロッパーとコミュニティと連携して、できるだけわかりやすく説明するようにします。これは、こちらの PR で明確ではなかったフォーム リソースの属性タイプの説明を収集するために行った投稿で行ったのと同様です。優先度の高い作業に取り組むため、メンターに相談し、ドキュメントに本当に価値を追加し、最初に達成する必要がある作業を決定します。

ユースケースを明示的な見出しとして追加する

私は、理解するために多くの API ドキュメントを見てきましたが、そのすべてに明示的な見出しとしてユースケースがあることがわかりました。ただし、明示的に表示されていないユースケースもありますが、リソースとサブリソースの定義の後に続く定義や例にある程度融合されています。ユースケースをドキュメントで別のエンティティとして分離する努力をすべきだと思います。これにより、デベロッパーはユースケースを調べる必要がなくなります。

  1. 不足しているリソースの検出と記録

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

結論

私は長い間 OpenMRS コミュニティに参加しています。私は Android クライアント プロジェクトに積極的に貢献しており、API を頻繁に使用してサーバーとやり取りしています。そのため、私は自分自身がデベロッパーとして自分の仕事を見ることができ、それが他のデベロッパーの作業を本当に楽にするかどうかを評価できるため、この API ドキュメントの拡張プロジェクトに取り組むことができると感じています。私は、ここでホストされているユーザー フレンドリーなドキュメント リポジトリで使用されているツールに精通しています。また、リポジトリとツール（slateUI など）に慣れるために、このリポジトリにもいくつかの貢献をしています。API はドキュメントと同じくらい優れていると考えられているため、ドキュメントを改善することで OpenMRS Rest API を少し改善したいと思います。

進捗状況については週に 1 回トークの投稿で伝えるようにしています。これはコミュニティからフィードバックを得て、メンターやコミュニティと緊密に連携してドキュメントを最大限に活用するのに役立ちます。