Projekt OpenMRS

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:

OpenMRS

Pisarz techniczny:

Saurabh

Nazwa projektu:

Rozszerzanie przyjaznej dla użytkownika dokumentacji GitHuba dla interfejsu API REST

Długość projektu:

Standardowa długość (3 miesiące)

Opis projektu

Główny cel

Rozszerz dokumentację interfejsu API REST OpenMRS Swagger, aby dodać wskazówki dotyczące korzystania z tego interfejsu.

Opis projektu

Interfejs API typu REST OpenMRS jest jednym z kluczowych mechanizmów umożliwiających programistom dostęp do danych z OpenMRS. Istnieje już automatycznie wygenerowana na podstawie Swagger dokumentacja interfejsu OpenMRS Webservices API oraz statyczna dokumentacja oparta na GitHubie. W tym sezonie udostępnimy dokumentację opartą na GitHubie.

KRÓTKI PRZEGLĄD

Po przeprowadzeniu badań w zakresie OpenMRS Talk zgodnie z sugestią Burke'a wiem, że ten projekt rozpoczął się w 2017 roku jako projekt GSOC. W projekcie Gayana Weerakutti głównym celem było ulepszenie dotychczasowej dokumentacji interfejsu API REST OpenMRS przez ulepszenie specyfikacji Swagger i ulepszenie sposobu generowania specyfikacji Swagger, aby umożliwić generowanie lepszej wersji dokumentacji. Wszystkie istotne szczegóły uzyskane w ramach projektu zostały podsumowane w tym poście z programu OpenMRS, co było dość przydatne.

Następnie w 2019 roku zmodyfikowaliśmy ten projekt i zaczęliśmy od wprowadzania poprawek w dokumentacji Swagger. Zamiast tego opracowaliśmy statyczną dokumentację dostosowaną do GitHuba, którą zamierzamy rozszerzyć w tym sezonie Dokumentów.

Obecna propozycja projektu, którą chcę opisać, to :

1. Przedstawiamy przykłady w niektórych popularnych językach (zwłaszcza Java i JavaScript).
2. Dodano obsługę dokumentacji planszy w placem zabaw, tak jak w przypadku funkcji „Wypróbuj” (Swagger).
3. refaktoryzowanie i ulepszanie dotychczasowych działań,
4. znajdowanie i dodawanie brakujących zasobów,
5. Dodanie nieco dodatkowego opisu do sekcji dokumentacji dotyczącej konsoli

SZCZEGÓŁOWY OPIS

1. Zaproponuj przykłady w różnych językach.

Sugeruję dodanie w języku Java przykładów opartych na SDK, a następnie dodanie przykładów wstecznych, które prawdopodobnie ubogacą naszą dokumentację. Dodanie przykładów w jeszcze jednym języku, takim jak JavaScript, nie pomoże tak bardzo jak dodanie przykładów retrospekcji, ponieważ używam tych interfejsów API REST podczas pracy z klientem OpenMRS na Androida. Za każdym razem, gdy potrzebna była pomoc w korzystaniu z punktów końcowych specjalnie dla Androida, nie było żadnych zasobów, które można by było znaleźć. Biorąc pod uwagę swoje doświadczenie w korzystaniu z punktów końcowych interfejsu OpenMRS API w kliencie Androida, mogę poważnie podać kilka przykładów wysokiej jakości. Omówię to z moimi mentorami i popracuję nad tym, co zostanie ustalone. Poza dodaniem przykładów obsługiwanych operacji warto też dodać przykłady uwierzytelniania za pomocą serwerów OpenMRS w niektórych językach programowania. Obecnie mamy tylko przykłady tego typu curl.

1. Dodanie obsługi funkcji Playground w przypadku przykładowych interfejsów API do testowania

Wykorzystałem tę funkcję w luksusowej dokumentacji OpenMRS na serwerze demonstracyjnym i jest to naprawdę wygodne narzędzie do stosowania w dowolnej dokumentacji API. Poszukałem(am) trochę informacji na ten temat i teraz trudno umieścić specyfikację Swagger-UI w obecnej statycznej dokumentacji. Używam przełączników pokazywania opcji ukrywania, a także aktualnego kodu z dokumentacji, Dzięki temu możemy nawet zadbać o to, aby testowana funkcja działała zgodnie z aktualnymi specyfikacjami interfejsu API. Wydaje mi się, że to jeden ze sposobów, w jaki możemy zintegrować z bieżącą statyczną dokumentację funkcje zabaw.

1. refaktoryzowanie i ulepszanie dotychczasowych działań,

Sprawdzanie bieżących przykładów curl

Ta sekcja jest jednym z głównych elementów tego projektu w tym roku. Obecnie w dokumentacji GitHub API znajdują się tylko przykłady curl, których niektórych nie można uruchomić bezpośrednio na serwerze demonstracyjnym, aby sprawdzić je bezpośrednio w przeglądarce. Przetestuję wszystkie bieżące punkty końcowe i utrzymam prosty dokument z różnymi przykładami curl, które otrzymujemy po uruchomieniu tych żądań curl. Aby wykonać to zadanie, w razie potrzeby użyję aplikacji Postman wraz z wbudowaną funkcją testowania podaną w dokumentacji elementów.

Brak odpowiedzi interfejsu API w niektórych przykładach

Dodano niektóre odpowiedzi do obecnych przykładów curl, ale niektóre z nich nie zawierają odpowiedzi. Myślę, że nawet jeśli odpowiedzi nie są wyczerpujące, co zwykle dzieje się w przypadku operacji takich jak trwałe usunięcie zasobu, powinniśmy podać przykładową odpowiedź interfejsu JSON API, ale udokumentowaliśmy wszystkie możliwe kody odpowiedzi i powody ich otrzymania. Sądzę, że dzięki temu przykłady w dokumentacji API będą bardziej jednolite.

Brak przykładów roboczych dotyczących różnych operacji

Sądzę, że to będzie najważniejsza część refaktoryzacji wcześniejszych działań w dokumentacji API. W dokumentacji znajdują się konkretne przykłady, które można wykonać bezpośrednio za pomocą cURL, ale niektóre z nich są nieco abstrakcyjne, co zapewnia dobry wgląd w doświadczenych programistów, ale wprawiają nowych użytkowników w problem. Z tego posta w prezentacji OpenMRS wynika, że dobre przykłady są bezcenne. Oprócz dodania przykładów pracy możemy obsługiwać wyróżnianie składni, które jest w rzeczywistości niezbyt trudne, można je dostrzec w pakiecie z planszą, co sprawia, że jest to dość proste.

Burke wielokrotnie podkreślał w swoim poście, że zamiast dobrego interfejsu i dobrego interfejsu w dokumentach preferuje prostotę i opisowość. Postaram się przestrzegać tych zasad i starać się, aby opisane wcześniej punkty końcowe były jak najbardziej opisowe, rozmawiając z programistami pracującymi obecnie nad interfejsem OpenMRS Webservices API i angażując społeczność tak jak w dyskusji, tak jak w dysku Zajmowałam się sprawami priorytetowymi, rozmawiałam z mentorami i rozmawiałam z mentorami, aby zdecydować, które z nich naprawdę zwiększają wartość dokumentów i które należy wykonać w pierwszej kolejności.

Dodanie przypadków użycia jako wyraźnego nagłówka

Widziałem wiele dokumentacji API, żeby je poznać, i widzę, że każdy z nich ma przypadki użycia jako jawny nagłówek, chociaż niektóre przypadki użycia nie są wyraźnie widoczne, ale są w pewien sposób umieszczone w definicjach i przykładach, które następują po definicjach zasobów i zasobów podrzędnych. Myślę, że powinniśmy spróbować oddzielić przypadki użycia jako osobne elementy w dokumentacji, tak aby deweloperzy mogli je tylko przeglądać.

1. Znajdowanie i dokumentowanie brakujących zasobów

   W obecnym stanie projektu wymienione są zasoby, ale po zapoznaniu się z najnowszą wersją dokumentacji udało mi się znaleźć wiele zasobów, które można dodać do obecnego zestawu zasobów. Opisaliśmy je w przypadku innych zasobów w Sezon of Docs 2019 i można je dodać do aktualnego zestawu zasobów. Omówię tematy, które należy dodać do dokumentów, i odpowiednio je dodaję.

PODSUMOWANIE

Już od jakiegoś czasu należę do społeczności OpenMRS. Jestem aktywnym uczestnikiem projektu klienta dla Androida, w którym często korzystam z interfejsów API, aby współpracować z serwerami. Wydaje mi się, że mogę pracować nad rozszerzeniem dokumentów API, bo mogę samodzielnie podejrzeć swoją pracę jako programistę i ocenić, czy to naprawdę ułatwia innym programistom pracę. Znam już narzędzia używane w tym łatwym dla użytkownika repozytorium z dokumentacją. W związku z tym, że mam sporo wkładu do tego repozytorium i narzędzi, uważam, że jego interfejs API jest lepszy od API. Moim zdaniem jest on lepiej przygotowany do ulepszenia SlateUI.

Będę informować o postępach co tydzień w formie postu, który pomoże poznać opinię społeczności i nawiązać bliską relację z mentorem oraz społecznością, aby jak najlepiej wykorzystać cały dostępny dokument.