Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- OpenMRS
- Pisarz techniczny:
- Saurabh
- Nazwa projektu:
- Rozszerzanie przyjaznej dla użytkownika dokumentacji GitHuba dotyczącej interfejsu API REST
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Cel główny
Ulepszyć dokumentację interfejsu API REST opartą na Swaggerze w OpenMRS, aby dodać wskazówki dotyczące korzystania z interfejsu API.
Opis projektu
Interfejs OpenMRS REST API jest jednym z kluczowych mechanizmów, które umożliwiają programistom dostęp do danych z OpenMRS. Dokumentacja interfejsu OpenMRS Webservices API jest już generowana automatycznie na podstawie Swaggera, a także w postaci statycznej w GitHub. W ramach tego sezonu chcemy rozszerzyć tę dokumentację w GitHub.
KRÓTKI OMÓWIENIE
Po przeanalizowaniu projektu OpenMRS Talk, jak zasugerował Burke, dowiedziałem się, że powstał on w 2017 roku jako projekt GSOC. Współpraca z Gayanem Weerakuttim, której głównym celem było ulepszenie istniejącej dokumentacji interfejsu OpenMRS REST API poprzez ulepszenie specyfikacji Swagger i sposobu jej generowania, aby uzyskać lepszą wersję samej dokumentacji Swagger. Wszystkie istotne szczegóły dotyczące projektu zostały podsumowane w tym poście na forum OpenMRS i były bardzo przydatne.
Następnie w 2019 roku ten projekt został odnowiony i poszliśmy od wprowadzenia zmian w dokumentacji Swagger, które dają różne możliwości. Zamiast tego opracowaliśmy stałą dokumentację w formacie przyjaznym dla GitHuba, którą rozszerzymy w tym sezonie Dokumentów.
Krótki opis obecnej propozycji projektu :
- Przykłady w popularnych językach (w tym w języku Java i JavaScript).
- Dodano obsługę playground dla dokumentacji slate, tak jak w przypadku funkcji „wypróbuj” w Swaggerze.
- Refaktoryzacja i ulepszanie dotychczasowej pracy.
- znajdowanie i dodawanie brakujących zasobów;
- Dodam więcej opisu w sekcji dotyczącej konsoli w dokumentacji.
SZCZEGÓŁOWY OPIS
- Przygotuj przykłady w różnych językach.
Proponuję dodanie przykładów w języku Java, które będą oparte na pakiecie SDK, a potem dodanie przykładów w ramach retrofit, które, jak sądzę, wzbogacą naszą dokumentację. Dodanie przykładów w jeszcze jednym języku, np. JavaScript, nie będzie tak pomocne jak dodanie przykładów w ramach retrofit, ponieważ używałem tych interfejsów API REST podczas pracy nad klientem OpenMRS na Androida i nie miałem do dyspozycji żadnych zasobów, do których mógłbym zajrzeć, gdy potrzebowałem pomocy w używaniu punktów końcowych na Androida. Moje doświadczenie w korzystaniu z punktów końcowych interfejsu OpenMRS interfejsu API w kliencie Androida to po prostu kilka przykładów dotyczących jakości. Porozmawiam o tym z moim mentorem i będę działać zgodnie z podjętą decyzją. Oprócz przykładów obsługiwanych operacji powinniśmy też dodać przykłady uwierzytelniania na serwerach OpenMRS w niektórych językach programowania. Obecnie mamy tylko przykłady skrętów.
- Dodanie obsługi Playground do przykładów testowania interfejsów API
Użyłem tej funkcji w dokumentacji swagger OpenMRS hostowanej na serwerze demonstracyjnym. To bardzo wygodne narzędzie, które warto mieć w dokumentacji interfejsu API. Po zapoznaniu się z tematem stwierdzam, że wstawienie specyfikacji Swagger-UI w bieżącej dokumentacji statycznej nie jest trudne. Używanie przełączników wyświetlania i ukrywania oraz korzystanie z obecnego kodu dokumentacji swagger. W ten sposób możemy nawet zapewnić, aby funkcja testowania była dostępna zgodnie z aktualnymi specyfikacjami interfejsu API. Jest to jeden ze sposobów na zintegrowanie funkcji playground z naszą obecną statyczną dokumentacją.
- Refaktoryzacja i ulepszanie dotychczasowej pracy
Sprawdzanie bieżących przykładów curl
Ta sekcja jest jednym z głównych tematów tego projektu w tym roku. Obecnie w dokumentach GitHub API znajdują się tylko przykłady curl, których nie można uruchomić bezpośrednio na serwerze demonstracyjnym, aby sprawdzić je bezpośrednio w przeglądarce. Będę testować wszystkie bieżące punkty końcowe i utrzymywać prosty dokument z różnymi odpowiedziami na przykładowe wywołania curl, które otrzymujemy po wykonaniu tych poleceń. W razie potrzeby użyję do tego celu programu Postman oraz wbudowanej funkcji testowania w dokumentacji swagger.
Brak odpowiedzi interfejsu API w niektórych przykładach
Do obecnych przykładów poleceń curl dodano niektóre odpowiedzi, ale niektóre z nich nie mają odpowiedzi. Uważam, że nawet jeśli odpowiedzi nie są obszerne, co zwykle ma miejsce w przypadku operacji takich jak oczyszczanie zasobu, powinniśmy mieć przykład odpowiedzi JSON API, mimo że mamy udokumentowane wszystkie możliwe kody odpowiedzi i ich przyczyny. Uważam, że dzięki temu przykłady w dokumentacji interfejsu API będą bardziej spójne.
Brak przykładów działania różnych operacji
Myślę, że będzie to najważniejsza część refaktoryzacji dokonanej wcześniej pracy w dokumentacji interfejsu API. W dokumentacji można znaleźć konkretne przykłady, które można wykonać bezpośrednio za pomocą cURL. Niektóre z nich są jednak nieco abstrakcyjne, co da dobre odniesienie do doświadczonych programistów, ale pozostawia w przypadku nowych programistów uciążliwe zasady. Z tego posta w OpenMRS wnioskuję, że dobre przykłady są bezcenne. Oprócz dodawania przykładów prac możemy też obsługiwać wyróżnianie składni, co nie wymaga wiele pracy, ponieważ jest to funkcja dołączona do Slate.
Burke wielokrotnie podkreślał w swoim poście, że zamiast dobrego interfejsu i błyszczącego interfejsu przestrzega tych zasad i postaram się, aby udokumentowane wcześniej punkty końcowe były jak najbardziej opisowe. W tym celu rozmawiaj z deweloperami, którzy obecnie pracują nad interfejsem OpenMRS Webservices API i angażują społeczność, tak jak w swoim poście o zbieraniu opisów typów atrybutów w materiałach, w przypadku których nie używam w tych formularzach jasnych opisów typów atrybutów w materiałach, które w przypadku moich zasobów nie były dla mnie jasne. Należy określić priorytety, porozmawiać z mentorami i zdecydować, które elementy naprawdę wzbogacają dokumenty i należy wykonać jako pierwsze.
Dodawanie przypadków użycia jako jednoznacznego nagłówka
Znam wiele dokumentacji API, żeby opanować ich umiejętność i zauważyłam, że wszystkie mają przypadki użycia w formie jawnego nagłówka, chociaż niektóre z nich nie są wyraźnie widoczne.
Znajdowanie i dokumentowanie brakujących zasobów
Aktualny stan projektu zawiera wymienione tutaj zasoby, ale po zapoznaniu się z najnowszą wersją dokumentacji swagger tutaj udało mi się znaleźć wiele zasobów, które można dodać do obecnego zestawu zasobów w dokumentacji interfejsu API na GitHubie, z opisem zrealizowanym w ramach Season of Docs 2019. Omówię tematy, które należy dodać do dokumentów, i odpowiednio je dodam.
PODSUMOWANIE
Od jakiegoś czasu uczestniczę w społeczności OpenMRS. Jestem aktywnym współtwórcą projektu Android Client, w którym często korzystam z interfejsów API do interakcji z serwerami. Dlatego uważam, że mogę pracować nad tym projektem rozszerzania dokumentacji interfejsu API, ponieważ mogę spojrzeć na moją pracę jako programisty i ocenić, czy naprawdę ułatwia ona pracę innym programistom. Znam narzędzia używane do tworzenia łatwej w użyciu repozytorium dokumentacji, które jest tutaj hostowane. Wniosłam też kilka poprawek do tego repozytorium, aby lepiej poznać repozytorium i narzędzie, np. slateUI. Ponieważ interfejs API jest tak dobry, jak jego dokumentacja, chciałabym nieco ulepszyć interfejsy API OpenMRS Rest, ulepszając ich dokumentację.
Będę co tydzień informować o postępach w tym zakresie, publikując posty z omówieniem, co pozwoli mi uzyskać opinie społeczności. Będę też ściśle współpracować z moim mentorem i społecznością, aby jak najlepiej wykorzystać ten okres dokumentacji.