OpenMRS-Projekt

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:
OpenMRS
Technischer Redakteur:
Saurabh
Projektname:
Nutzerfreundliche GitHub-Dokumentation für die REST API erweitern
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

Primäres Ziel

Die auf OpenMRS Swagger basierende REST API-Dokumentation erweitern, um Anleitungen zur Verwendung der API hinzuzufügen.

Projektbeschreibung

Die OpenMRS REST API ist einer der wichtigsten Mechanismen, mit denen Entwickler auf OpenMRS-Daten zugreifen können. Es gibt bereits eine automatisch auf Swagger basierende, automatisch generierte Dokumentation der OpenMRS Webservices API und eine statische GitHub-basierte Dokumentation. Diese GitHub-basierte Dokumentation sollen in dieser Season of Docs erweitert werden.

KURZÜBERSICHT

Nach ein wenig Recherche zu OpenMRS Talk, wie Burke sagte, erfuhr ich, dass dieses Projekt 2017 als GSOC-Projekt begann. Mit Gayan Weerakutti bestand das Hauptziel darin, die vorhandene Dokumentation der OpenMRS REST API zu verbessern, indem die Swagger-Spezifikation verbessert und die Art der Generierung der Swagger-Spezifikation verbessert wurde, um eine bessere Version der Swagger-Dokumentation zu generieren. Alle relevanten Details, die im Rahmen des Projekts erreicht wurden, wurden hier in diesem OpenMRS-Gesprächsbeitrag zusammengefasst und waren sehr hilfreich.

2019 wurde dieses Projekt dann überarbeitet und wir haben die Swagger-Dokumentationen überarbeitet und daraus Varianten davon erstellt. Stattdessen haben wir eine statische GitHub-freundliche Dokumentation entwickelt, die wir in dieser Version von Google Docs erweitern werden.

Ein kurzer Überblick über den aktuellen Projektvorschlag, den ich beschreiben möchte, lautet :

  1. Ich erarbeite Beispiele in einigen gängigen Sprachen (insbesondere Java und JavaScript).
  2. Playground-Unterstützung für die Slate-Dokumentation wie die „Probefunktion“ von Swagger hinzufügen
  3. Die bisher geleistete Arbeit wird refaktoriert und verbessert.
  4. Fehlende Ressourcen suchen und hinzufügen
  5. Eine genauere Beschreibung zum Konsolenabschnitt der Dokumente hinzufügen

DETAILLIERTE BESCHREIBUNG

  1. Denken Sie sich Beispiele in verschiedenen Sprachen aus.

Ich würde vorschlagen, SDK-basierte Beispiele in Java hinzuzufügen und dann Retrofit-Beispiele hinzuzufügen, die unsere Dokumentation meiner Meinung nach detaillierter gestalten. Das Hinzufügen von Beispielen in einer weiteren Sprache wie JavaScript ist nicht so hilfreich wie das Hinzufügen von Retrofit-Beispielen, da ich diese REST APIs während der Arbeit am OpenMRS Android Client verwendet habe und es keine Ressourcen gab, auf die ich nachschlagen konnte, wenn ich Hilfe bei der Verwendung der Endpunkte speziell für Android brauchte. Und aufgrund meiner Erfahrung mit OpenMRS-API-Endpunkten im Android-Client könnte ich hier ernsthaft einige hochwertige Beispiele nennen. Ich werde dies mit meinen Mentoren besprechen und an der Entscheidung arbeiten. Neben Beispielen für die unterstützten Vorgänge sollten wir auch Beispiele für die Authentifizierung bei OpenMRS-Servern in einigen Programmiersprachen hinzufügen. Derzeit haben wir hierfür nur curl-Beispiele.

  1. Playground-Unterstützung für das Testen von APIs – Beispiele hinzufügen

Ich habe diese Funktion in der auffälligen Dokumentation von OpenMRS verwendet, das auf dem Demo-Server gehostet wird. Es ist ein wirklich praktisches Tool, das in jeder API-Dokumentation enthalten sein kann. Ich habe hier ein wenig recherchiert und es ist nicht so schwierig, die Swagger-UI-Spezifikationen in die aktuelle statische Dokumentation einzubetten. Verwendung der Ein-/Aus-Schaltflächen zum Einblenden/Ausblenden und Verwenden des aktuellen Dokumentationscodes für Swagger. Auf diese Weise können wir sogar dafür sorgen, dass die Testfunktion mit den aktuellen API-Spezifikationen verfügbar bleibt. Dies ist eine Möglichkeit, denke ich, dass wir Playground-Funktionen in unsere aktuelle statische Dokumentation integrieren können.

  1. Refaktorierung und Verbesserung der bisherigen Arbeit
Aktuelle curl-Beispiele überprüfen

Dieser Abschnitt ist einer der Hauptschwerpunkte dieses Projekts in diesem Jahr. Derzeit gibt es nur curl-Beispiele in den GitHub API-Dokumenten. Einige davon können nicht direkt auf dem Demoserver ausgeführt werden, um sie direkt im Browser zu überprüfen. Ich teste alle aktuellen Endpunkte und pflege ein einfaches Dokument mit den Antworten verschiedener curl-Beispiele, die wir beim Ausführen dieser curl-Anfragen erhalten. Ich werde neben der integrierten Testfunktion in der Swagger-Dokumentation Postman verwenden, um diese Aufgabe bei Bedarf auszuführen.

Bei einigen Beispielen fehlen API-Antworten

Für die vorliegenden curl-Beispiele wurden einige Antworten hinzugefügt, aber für einige curl-Beispiele gibt es keine Antworten. Ich denke, auch wenn die Antworten nicht ausführlich sind, was normalerweise bei Vorgängen wie dem Löschen der Ressource der Fall ist, sollten wir ein Beispiel für eine JSON-API-Antwort haben, obwohl wir alle möglichen Antwortcodes und den Grund für deren Erhalt dokumentiert haben. Ich denke, dies würde die Beispiele in der gesamten API-Dokumentation einheitlicher machen!!

Fehlende Arbeitsbeispiele für verschiedene Vorgänge

Ich denke, dies wird der wichtigste Teil der Refaktorierung der zuvor geleisteten Arbeit in der API-Dokumentation sein. Es gibt konkrete Beispiele in der Dokumentation, die direkt mit cURL ausgeführt werden können, aber einige davon sind etwas abstrakt, was eine gute Referenz für erfahrene Entwickler bietet, aber die Neuankömmlinge in Schwung bringt. Wie ich in diesem Beitrag in OpenMRS erkennen konnte, dass gute Beispiele unbezahlbar sind. Abgesehen von den Beispielen für die Arbeit können wir die Syntaxhervorhebung unterstützen. Das ist in der Tat nicht viel Arbeit, es ist eher in Slates gebündelt, was dies recht einfach macht, wie ich hier herausgefunden habe.

Da Burke in seinem Beitrag schon oft betont hat, dass Einfachheit und Aussagekraft in Dokumenten statt einer guten Benutzeroberfläche und einer glänzenden Oberfläche lieber sind, würde ich mich an diese Grundsätze halten und versuchen, die zuvor dokumentierten Endpunkte so beschreibend wie möglich zu gestalten. Dazu spreche ich mit Entwicklern, die derzeit an der OpenMRS Webservices API arbeiten, und interagiere mit der Community, genau wie in dem Gesprächsbeitrag zum Sammeln von Beschreibungen für die Attributtypen für die hier für die PR verwendeten Ressourcen. Ich würde wirklich vorrangig an Dingen arbeiten, mit meinen Mentoren sprechen und entscheiden, welche Aspekte den Dokumenten wirklich einen Mehrwert bieten und zuerst erledigt werden müssen.

Anwendungsfälle als eindeutige Überschrift hinzufügen

Ich habe viele API-Dokumentationen gesehen, nur um sie zu verstehen. Ich habe gesehen, dass alle Anwendungsfälle als eindeutige Überschrift angegeben wurden. Obwohl wir Anwendungsfälle haben, sind sie nicht explizit sichtbar, aber sie sind etwas in die Definitionen und Beispiele eingebunden, die nach den Definitionen der Ressourcen und Unterressourcen folgen. Ich denke, wir sollten Anwendungsfälle als separate Einheit in der Dokumentation trennen, damit Entwickler die Anwendungsfälle nicht wirklich durchsuchen müssen.

  1. Fehlende Ressourcen finden und dokumentieren

    Im aktuellen Projektstatus sind hier Ressourcen aufgeführt. Da ich jedoch die aktuelle Version der Swagger-Dokumentation hier sehe, konnte ich viele Ressourcen ermitteln, die der aktuellen Ressourcen-Suite in den GitHub-freundlichen API-Dokumenten mit der Beschreibung hinzugefügt werden könnten, die während der Season of Docs 2019 mit anderen Ressourcen erreicht wurde. Ich werde die Themen besprechen, die den Dokumenten hinzugefügt werden müssen, und sie entsprechend hinzufügen.

ZUSAMMENFASSUNG

Ich bin schon seit einiger Zeit Teil der OpenMRS-Community. Ich bin ein aktiver Beitragender für das Android Client-Projekt, bei dem ich häufig mit den APIs interagiere, um mit den Servern zu interagieren. Daher glaube ich, dass ich an diesem Projekt zur Erweiterung der API-Dokumente ziemlich gut mitarbeiten kann,da ich meine Arbeit als Entwickler selbst sehen und beurteilen kann, ob es die Arbeit anderer Entwickler wirklich erleichtert oder nicht.Ich habe mich mit den Tools für das hier gehostete nutzerfreundliche Dokumentations-Repository vertraut gemacht. Ich habe auch mehrere Beiträge zu diesem Repository geleistet, um mich mit dem Repository und den Tools vertraut zu machen.

Ich werde den Fortschritt wöchentlich in einem Gesprächsbeitrag kommunizieren, der dazu beiträgt, Feedback von der Community zu erhalten und eng mit meinem Mentor und der Community zusammenzuarbeiten, um aus dieser Dokumentationsphase das Beste herauszuholen.