Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- OpenMRS
- Pisarz techniczny:
- Saurabh
- Nazwa projektu:
- Rozszerzanie przyjaznej dla użytkownika dokumentacji GitHub API dla interfejsu API REST
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Główny cel
Rozszerz dokumentację interfejsu API REST opartego na OpenMRS Swagger, aby dodać wskazówki dotyczące korzystania z tego interfejsu.
Opis projektu
Interfejs OpenMRS API typu REST to jeden z kluczowych mechanizmów umożliwiających programistom dostęp do danych z OpenMRS. Istnieje już automatycznie wygenerowana dokumentacja interfejsu OpenMRS Webservices API w narzędziu Swagger oraz statyczna dokumentacja oparta na GitHubie. W tym sezonie Dokumentów mamy rozszerzyć ten zbiór dokumentów opartych na GitHubie.
KRÓTKI PRZEGLĄD
Po przeprowadzeniu badań nad OpenMRS Talk zgodnie z sugestią Burke'a dowiedziałam się, że ten projekt rozpoczął się w 2017 r. jako projekt GSOC. W przypadku Gayan Weerakutti głównym celem było ulepszenie istniejącej dokumentacji interfejsu OpenMRS API typu REST przez ulepszenie specyfikacji Swagger i ulepszenie sposobu generowania specyfikacji Swagger, tak aby generowana była lepsza dokumentacja tego interfejsu. Wszystkie istotne szczegóły uzyskane w ramach projektu zostały podsumowane w tym poście z prezentu OpenMRS i są bardzo przydatne.
Następnie w 2019 r. zmodernizowaliśmy ten projekt i zaczęliśmy od wprowadzania zmian w dokumentacji Swagger. Zamiast tego opracowaliśmy statyczną, przyjazną dla GitHub dokumentację, którą będziemy rozszerzać w tym sezonie Dokumentów.
Obecna propozycja projektu, którą chcę opisać, to :
- Opracowanie przykładów w kilku popularnych językach (zwłaszcza Java i JavaScript).
- Dodano obsługę dokumentacji planszy w ramach placu zabaw, tak jak w przypadku funkcji Swagger „wypróbuj”.
- Refaktoryzacja i ulepszanie dotychczasowych zadań.
- znajdowanie i dodawanie brakujących zasobów,
- Dodano nieco więcej opisu do sekcji konsoli w dokumentacji
SZCZEGÓŁOWY OPIS
- Zaproponuj przykłady w różnych językach.
Zasugerowałbym dodanie przykładów w Javie, które będą oparte na SDK, a następnie dodanie przykładów modernizacji, które moim zdaniem znacznie wzbogacą 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 w kliencie OpenMRS na Androida. Za każdym razem, gdy potrzebowałam pomocy w korzystaniu z punktów końcowych specjalnie dla Androida, nie można było znaleźć zasobów. Biorąc pod uwagę moje doświadczenie w pracy z punktami końcowymi interfejsu OpenMRS API w kliencie Androida, będę w stanie podać tu kilka przykładów wysokiej jakości. Omówię to z moimi mentorami i popracuję nad tym, co zostanie podjęte. Poza przykładami obsługiwanych operacji powinniśmy także dodać przykłady uwierzytelniania za pomocą serwerów OpenMRS w niektórych językach programowania. Obecnie mamy do tego tylko przykłady curl.
- Dodanie obsługi funkcji Playground do testowania przykładów interfejsów API
Użyłem tej funkcji w eleganckiej dokumentacji OpenMRS hostowanej na serwerze demonstracyjnym. Jest to bardzo wygodne narzędzie, które można zastosować w dowolnej dokumentacji API. Poświęciłem trochę czasu i zauważyłem, że umieszczenie specyfikacji Swagger-UI w obecnej statycznej dokumentacji nie jest trudne. Używanie przełączników „Pokaż ukrywanie” i używanie aktualnego kodu z dokumentacji funkcji „Swagger”. W ten sposób możemy nawet zadbać o to, aby funkcja testowa działała zgodnie z aktualnymi specyfikacjami interfejsu API. Wydaje mi się, że możemy zintegrować z naszą obecną dokumentację statyczną, funkcje placów zabaw.
- Refaktoryzacja i ulepszanie dotychczasowej pracy
Sprawdzam bieżące przykłady curl
Ta sekcja jest jednym z głównych aspektów tego projektu w tym roku. Obecnie w dokumentacji interfejsu GitHub API znajdują się tylko przykłady curl. Niektórych z nich 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 utworzę prosty dokument z różnymi przykładami curl, które uzyskasz po uruchomieniu tych żądań curl. W razie potrzeby użyję Postmana jako dodatku do wbudowanej funkcji testowania dostępnej w dokumentacji z narzędzia Swagger.
Brak odpowiedzi interfejsu API w niektórych przykładach
Niektóre odpowiedzi zostały dodane do obecnych przykładów curl, ale niektóre z nich nie mają odpowiedzi. Myślę, że nawet jeśli odpowiedzi nie są szczegółowe, co zwykle dzieje się w przypadku operacji takich jak trwałe usunięcie zasobu, powinniśmy mieć przykładową odpowiedź interfejsu JSON API. Mimo to udokumentowaliśmy wszystkie możliwe kody odpowiedzi i informacje o powodach ich uzyskania. 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
Myślę, że będzie to najważniejsza część refaktoryzacji dotychczasowych 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 stanowi dobry punkt odniesienia do doświadczonych programistów, ale zniechęca nowych użytkowników. Z tego posta na temat OpenMRS mogę się dowiedzieć, że dobre przykłady są bezcenne, więc oprócz przykładów pracy możemy obsługiwać wyróżnianie składni, które w rzeczywistości nie jest zbyt pracochłonne. Jest to możliwe w pakiecie z planszą, co sprawia, że jest to całkiem łatwe.
Jak mawiał w swoim poście Burke wiele razy, w swoim poście kładzie się nacisk na prostotę i opisowość zamiast dobrego UI i błyszczącego interfejsu. Postaram się przestrzegać tych zasad i zadbać o to, aby wcześniej udokumentowane punkty końcowe były jak najbardziej opisowe, rozmawiając z programistami, którzy obecnie pracują nad interfejsem OpenMRS Webservices API, i zaangażując społeczność, tak jak w poście na forum, aby zbierać opisy typów atrybutów dla moich formularzy PR, które nie były tu oczywiste. Rozmawiam z mentorami i rozmawiam z mentorami, podejmując decyzje o tym, co naprawdę przyczyni się do zwiększenia wartości dokumentów, a które należy wykonać w pierwszej kolejności.
Dodawanie przypadków użycia jako jednoznacznego nagłówka
Widziałem wiele dokumentacji API, aby się z nimi zapoznać, i widzę, że każdy z nich ma przypadki użycia jako jawny nagłówek, choć niektóre przypadki użycia nie są wyraźnie widoczne, ale są w pewien sposób umieszczone w definicjach i przykładach, które występują po definicjach zasobów i zasobów podrzędnych. Myślę, że lepiej będzie oddzielić przypadki użycia jako osobne elementy w dokumentacji, aby deweloperzy nie musieli ich przeszukujeć.
Znajdowanie i dokumentowanie brakujących zasobów
Obecny stan projektu zawiera wymienione tutaj zasoby, ale przeglądając najnowszą wersję dokumentacji Swagger, odkryłem wiele zasobów, które można dodać do bieżącego zestawu zasobów. Znajdziesz je w dokumentacji interfejsu API GitHuba z opisem tak samo jak w przypadku innych zasobów z sezonu Dokumentów 2019. 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 obsługiwać serwery. Wydaje mi się, że mogę pracować nad projektem rozbudowy dokumentacji API, bo mogę samodzielnie spojrzeć na swoją pracę jako programista i ocenić, czy to naprawdę ułatwia pracę innym programistom.Znam już narzędzia wykorzystywane w tym łatwym w obsłudze repozytorium z dokumentacją. Właśnie udało mi się wzbogacić to repozytorium, by zapoznać się z repozytorium i narzędziami, które – jako interfejs API – uważam, że są w nim lepiej.
Będę informować o postępach co tydzień za pomocą postu, który pomoże uzyskać opinie społeczności i nawiąż bliską relację z mentorem oraz społecznością, aby jak najlepiej wykorzystać ten okres dokumentacji.