Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- OpenMRS
- Technischer Redakteur:
- Saurabh
- Projektname:
- Nutzerfreundliche GitHub-Dokumentation für die REST API erweitern
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
Primäres Ziel
Erweitern Sie die Dokumentation zur OpenMRS Swagger-basierten REST API, um Hinweise zur Verwendung der API hinzuzufügen.
Projektbeschreibung
Die OpenMRS REST API ist einer der wichtigsten Mechanismen für Entwickler, um auf Daten aus OpenMRS zuzugreifen. Es gibt bereits eine automatisch generierte Swagger-basierte Dokumentation der OpenMRS Webservices API und eine statische GitHub-basierte Dokumentation. Wir sollen diese GitHub-basierte Dokumentation in dieser Season of Docs erweitern.
KURZÜBERSICHT
Nachdem ich wie von Burke vorgeschlagen OpenMRS Talk recherchiert hatte, erfuhr ich, dass dieses Projekt bereits 2017 als GSOC-Projekt gestartet wurde. Gayan Weerakutti, bei dem es vor allem darum ging, die vorhandene Dokumentation der OpenMRS REST API zu verbessern, indem die Swagger-Spezifikation und die Art und Weise, wie sie generiert wird, verbessert wurden, um eine bessere Version der Swagger-Dokumentation zu generieren. Alle relevanten Details, die im Projekt erreicht wurden, wurden hier in diesem OpenMRS-Talk-Beitrag zusammengefasst und waren sehr nützlich.
2019 wurde das Projekt dann umgestaltet und wir haben Änderungen an der Swagger-Dokumentation vorgenommen. Stattdessen haben wir eine statische, GitHub-kompatible Dokumentation entwickelt, die wir in dieser Saison der Docs erweitern werden.
Hier eine Zusammenfassung des aktuellen Projektvorschlags, die ich beschreiben möchte :
- Beispiele in einigen gängigen Programmiersprachen (insbesondere Java und JavaScript) nennen
- Unterstützung für den Playground für die Slate-Dokumentation hinzufügen, ähnlich wie bei der Swagger-Funktion „Try-out“
- Refaktorierung und Verbesserung der bisher geleisteten Arbeit.
- Fehlende Ressourcen finden und hinzufügen
- Der Abschnitt zur Console in der Dokumentation wurde etwas ausführlicher beschrieben.
DETAILLIERTES BESCHREIBNIS
- Beispiele in verschiedenen Sprachen finden
Ich würde vorschlagen, Beispiele in Java hinzuzufügen, die SDK-basiert sind, und dann Retrofit-Beispiele hinzuzufügen, die unserer Dokumentation mehr Tiefe verleihen. Das Hinzufügen von Beispielen in einer weiteren Sprache wie JavaScript ist nicht so hilfreich wie das Hinzufügen von Retrofit-Beispielen. Ich habe diese REST APIs bei der Arbeit am OpenMRS Android-Client verwendet und es gab keine Ressourcen, auf die ich zurückgreifen konnte, wenn ich Hilfe bei der Verwendung der Endpunkte speziell für Android brauchte. Und ich könnte hier einige gute Beispiele nennen, da ich Erfahrung mit OpenMRS API-Endpunkten im Android-Client habe. Ich werde das mit meinen Mentoren besprechen und an der Entscheidung arbeiten. Außerdem sollten wir nicht nur Beispiele für die unterstützten Vorgänge hinzufügen, sondern auch Beispiele für die Authentifizierung bei OpenMRS-Servern in einigen Programmiersprachen. Derzeit gibt es nur curl-Beispiele dafür.
- Playground-Unterstützung zum Testen von API-Beispielen hinzufügen
Ich habe diese Funktion in der Swagger-Dokumentation von OpenMRS verwendet, die auf dem Demoserver gehostet wird. Es ist ein sehr praktisches Tool für jede API-Dokumentation. Ich habe ein wenig recherchiert und es ist gar nicht so schwierig, die Swagger-UI-Spezifikation in die aktuelle statische Dokumentation einzubetten. Mit Ein-/Aus-Schaltflächen und dem aktuellen Code der Swagger-Dokumentation. Auf diese Weise können wir sogar sicherstellen, dass die Testfunktion mit den aktuellen API-Spezifikationen verfügbar bleibt. Ich denke, dies ist eine Möglichkeit, die Playground-Funktionen in unsere aktuelle statische Dokumentation zu integrieren.
- Die bisher geleistete Arbeit überarbeiten und verbessern
Aktuelle curl-Beispiele prüfen
Dieser Abschnitt ist einer der Schwerpunkte dieses Projekts in diesem Jahr. Derzeit sind in der GitHub API-Dokumentation nur Curl-Beispiele verfügbar, von denen einige nicht direkt auf dem Demoserver ausgeführt werden können, um sie direkt im Browser zu prüfen. Ich werde alle aktuellen Endpunkte testen und ein einfaches Dokument mit den Antworten verschiedener Curl-Beispiele führen, die wir beim Ausführen dieser Curl-Anfragen erhalten. Ich verwende zusätzlich zur integrierten Testfunktion in der Swagger-Dokumentation Postman, um diese Aufgabe auszuführen.
In einigen Beispielen fehlen API-Antworten.
Für die vorliegenden curl-Beispiele wurden einige Antworten hinzugefügt, für einige curl-Beispiele gibt es jedoch 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 eine JSON API-Beispielantwort haben, obwohl wir alle möglichen Antwortcodes und den Grund für den Erhalt dokumentiert haben. Ich denke, dadurch würden die Beispiele in der API-Dokumentation einheitlicher werden.
Fehlende funktionierende Beispiele für verschiedene Vorgänge
Ich denke, dies wird der wichtigste Teil der Refaktorierung der zuvor in der API-Dokumentation erreichten Arbeit sein. In der Dokumentation finden Sie konkrete Beispiele, die direkt mit cURL ausgeführt werden können. Einige davon sind jedoch etwas abstrakt, was eine gute Referenz für erfahrene Entwickler bietet, aber Neuankömmlinge in einem Nervenkitzel stört. Wie ich in diesem Beitrag im OpenMRS-Vortrag erfahren habe, sind gute Beispiele unbezahlbar. Abgesehen von den Arbeitsbeispielen können wir die Syntaxhervorhebung unterstützen, was in der Tat nicht viel Arbeit ist. Die Anwendung wird in Slates eingebunden, was die Umsetzung so einfach macht, wie ich hier herausgefunden habe.
Wie Burke in seinem Beitrag oft betont hat, bevorzugt er Einfachheit und Beschreibungskraft in Dokumenten anstelle einer guten Benutzeroberfläche und einer glänzenden Oberfläche. Ich würde mich an diese Prinzipien halten und versuchen, die zuvor dokumentierten Endpunkte so beschreibend wie möglich zu gestalten, indem ich mit Entwicklern spreche, die derzeit an der OpenMRS Webservices API arbeiten, und die Community einbinde, so wie ich es im Talkpost getan habe, um Beschreibungen für die Attributtypen für die Formularressourcen zu erhalten, die mir in meiner PR hier nicht klar waren. Ich würde die Aufgaben nach Priorität sortieren, mit meinen Mentoren sprechen und entscheiden, welche Dinge den Dokumenten wirklich einen Mehrwert verleihen und zuerst erledigt werden müssen.
Anwendungsfälle als explizite Überschrift hinzufügen
Ich habe mir viele API-Dokumente angesehen, um sie besser kennenzulernen, und festgestellt, dass alle Anwendungsfälle als explizite Überschrift hatten. Wir haben zwar Anwendungsfälle, die aber nicht explizit sichtbar sind, sondern in den Definitionen und Beispielen, die nach den Definitionen der Ressourcen und Unterressourcen folgen, etwas verschmolzen sind. Ich denke, wir sollten uns die Mühe machen, Anwendungsfälle in der Dokumentation als separate Entität zu trennen, damit Entwickler nicht wirklich durch die Definitionen suchen müssen, um die Anwendungsfälle zu ermitteln, sondern sie einfach nachschlagen können.
Fehlende Ressourcen finden und dokumentieren
Für den aktuellen Projektstatus sind hier Ressourcen aufgeführt, aber als ich hier die neueste Version der Swagger-Dokumentation sah, konnte ich viele Ressourcen finden, die der aktuellen Ressourcensuite in der GitHub-freundlichen API-Dokumentation hinzugefügt werden könnten. Die Beschreibung wurde in der Season of Docs 2019 in anderen Ressourcen umgesetzt. 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 aktiv am Android Client-Projekt beteiligt, bei dem ich häufig mit den APIs interagiere, um mit den Servern zu interagieren. Daher bin ich der Meinung, dass ich an diesem Projekt zur Erweiterung der API-Dokumente ziemlich gut arbeiten kann, da ich meine Arbeit als Entwickler selbst betrachten und bewerten kann, ob sie die Arbeit anderer Entwickler wirklich erleichtert oder nicht. Ich habe mich mit den Tools vertraut gemacht, die für das nutzerfreundliche Dokumentationsverzeichnis verwendet werden, das hier gehostet wird. Ich habe auch mehrere Beiträge zu diesem Repository geleistet, um mich mit dem Repository und den Tools vertraut zu machen, z. B. slateUI. Da eine API so gut ist wie ihre Dokumentation, würde ich die OpenMRS Rest APIs gerne ein wenig verbessern, indem ich ihre Dokumentation verbessere.
Ich werde die Fortschritte wöchentlich in einem Talkpost mitteilen, um Feedback von der Community zu erhalten. Außerdem werde ich eng mit meinem Mentor und der Community zusammenarbeiten, um diese Dokumentationsphase optimal zu nutzen.