Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.
Podsumowanie projektu
- Organizacja open source:
- OpenMRS.org
- Specjalista ds. technicznych:
- batbrain7
- Nazwa projektu:
- Dokumentacja interfejsu OpenMRS API REST
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Podzielę ofertę na różne sekcje i postępuję zgodnie z procedurą, taką jak dokumentacja interfejsu API Map Google i dokumentacja interfejsu GitHub API.
Oprócz tego proponuję też strukturę pliku readme dla dokumentacji interfejsu API, która została przygotowana przez realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Osobiście uważam, że ta dokumentacja jest bardzo łatwa do zrozumienia i zastosowania.
Moja propozycja składałaby się głównie z 3 sekcji :
Sekcja zawierająca krótkie wprowadzenie o interfejsie API, o OpenMRS i sposobie jego używania oraz o dalszych działaniach.
Uzyskiwanie klucza interfejsu API i ogólnie uwierzytelnianie potrzebne do wysyłania żądania do interfejsu API. Będzie to przykładowy przykład typów uwierzytelniania w interfejsie API oraz kluczy i wartości, które muszą być w nim obecne, a także typów wartości akceptowanych przez klucz w danej części. Przykładowy kod w dowolnym języku pomoże Ci zrozumieć, jak tworzyć nagłówki i formaty odpowiedzi oraz inne parametry zapytań w interfejsie API.
Należy wspomnieć o typach odpowiedzi, które pobiera interfejs API, typach danych JSON lub dowolnym innym typie wyniku zwracanym przez interfejsy API.
różne ścieżki interfejsu API oraz wszystkie parametry, które należy przesłać wraz z tymi ścieżkami, nagłówki i inne elementy. Każdy interfejs API będzie zawierać przykłady kodu w kilku językach, które opisują, jak tworzyć żądanie podczas pisania kodu. Oprócz tego należy również podać ogólne kody błędów, które mogą wystąpić w przypadku każdego interfejsu API.
Oto ogólny zarys tego, jak będzie wyglądać dokumentacja interfejsu API REST.
Harmonogram projektu :
1 sierpnia – 1 września
Poznaj mojego mentora i porozmawiaj z nim o tym, jaki poziom dokumentacji jest wymagany w różnych częściach kodu źródłowego, a także o tym, jak szczegółowo opisać dokumentację na poziomie niskiego poziomu i wyższego poziomu. W tym czasie będę też poznawać kod źródłowy i analizować pojęcia, aby lepiej je udokumentować.
Tydzień 1 i 2
Zaktualizuję i rozszerzę przewodnik dla autorów. Poprawię dokumentację dotyczącą kompilowania kodu źródłowego. Dodam też sekcję z dokumentami, z której dowiesz się, jak nowi współtwórcy mogą pomóc w tworzeniu dokumentacji. Zapoznam się z różnymi dokumentacjami interfejsów API, zacznę od wprowadzenia i dodam uwierzytelnianie dla interfejsu API.
Tydzień 3–8
Dodam trasy i odpowiedzi interfejsu API oraz przykłady kodu dla każdego typu interfejsu API (mogą występować podobne typy interfejsów API).
Tydzień 9 i 10
Dodaj strukturę dokumentacji interfejsu API z użyciem linków, tj.indeksów połączonych z obszerną dokumentacją interfejsu API, i podziel ją na różne sposoby, na przykład na podstawie sekcji kodu, omówienia, parametrów, głównych punktów końcowych.
Ostatni tydzień
Ostatni tydzień wykorzystam na przygotowanie końcowego raportu z wyników pracy w ciągu 12 tygodniowego okresu dokumentowania. Wykorzystam ten czas na sprawdzenie i dopracowanie dokumentacji.