OpenMRS プロジェクト

このページには、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 で少し調べた結果、このプロジェクトが GSOC プロジェクトとして 2017 年に始まったことを知りました。Gayan Weerakutti では、OpenMRS REST API の既存のドキュメントを改善することを主な目的として、Swagger 仕様を改善し、Swagger ドキュメント自体のより優れたバージョンが生成されるように Swagger 仕様の生成方法を改善しました。プロジェクトで達成された関連する詳細情報はすべて、この OpenMRS のトーク投稿に要約されており、非常に有益でした。

その後、2019 年にこのプロジェクトを刷新し、Swagger のドキュメントに微調整を加え、これにバリエーションを持たせました。代わりに、GitHub 用の静的なドキュメントを作成しました。Google ドキュメントの今シーズンには、この機能を拡張する予定です。

これから説明するプロジェクト提案の概要は次のとおりです。

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

詳細な説明

  1. さまざまな言語で例を考えてみます。

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

  1. テスト用の API サンプルに対するプレイグラウンドのサポートの追加

デモサーバーでホストされている 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 のトークに関するこの投稿からわかったように、優れた例は貴重です。作業例の追加は別として、構文のハイライト表示をサポートできます。これは実際にはあまり機能しませんが、スレートにバンドルされているため、ここで確認したように簡単に実行できます。

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

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

私は、コツをつかむために多くの API ドキュメントを見てきました。そして、そのすべてに明確な見出しとしてユースケースがあることがわかりました。しかし、明示的には見えないユースケースもありますが、これらはリソースとサブリソースの定義の後に続く定義と例の中に多少融合されています。 ユースケースを個別のエンティティとしてドキュメント内で分離する努力が必要で、開発者が実際に検索する必要がないようにしましょう。

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

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

結論

私は以前から OpenMRS コミュニティに参加しています。Android クライアント プロジェクトに積極的に貢献しており、API を頻繁に操作してサーバーとやり取りしています。したがって、自分のデベロッパーとして自分の作業を確認し、他のデベロッパーの作業が本当に楽になるかどうかを評価できるため、API ドキュメントを拡張するこのプロジェクトに取り組めると思います。また、ここでホストされているユーザー フレンドリーなドキュメント リポジトリに使用されるツールに慣れてきたので、このリポジトリにいくつか貢献して、ドキュメントを改善して API ドキュメントを改善します。

進捗状況については、コミュニティからフィードバックを得るのに役立つトーク投稿で毎週お伝えします。また、この期間のドキュメントを最大限に活用できるよう、メンターやコミュニティと密接に連携して取り組みます。