Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- OpenMRS.org
- Pisarz techniczny:
- batbrain7
- Nazwa projektu:
- Dokumentacja interfejsu OpenMRS REST API
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Podzielę ofertę na różne sekcje i będę postępować zgodnie z tym schematem, np. z dokumentacją interfejsu API Map Google i dokumentacją interfejsu GitHub API.
Poza tym chcę też zaproponować strukturę pliku Readme dla dokumentacji interfejsu API, którą tworzy realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Osobiście uważam tę dokumentację za bardzo łatwa do zrozumienia i korzystania.
Moja propozycja składałaby się głównie z 3 sekcji :
Sekcja, która zawiera krótkie wprowadzenie na temat API, OpenMRS i sposobów jego używania oraz co dalej.
Jak uzyskać klucz interfejsu API i ogólnie uwierzytelnianie potrzebne do wysłania żądania do API. Zobaczysz przykładowy przykład typów uwierzytelniania dostępnych w interfejsie API oraz klucze i wartości, które muszą być dostępne w przypadku tego interfejsu, a także typy akceptowanych wartości odpowiadające kluczowi w tej części. Przykładowy kod w dowolnym języku pomoże Ci pisać nagłówki i formaty odpowiedzi oraz inne parametry zapytania w interfejsie API.
Wymienione zostaną typy odpowiedzi pobieranych przez interfejs API, typy JSON oraz dowolne inne typy wyników zwracanych przez interfejsy API.
Różne trasy interfejsu API i informacje, jakie należy wysyłać razem z nimi, nagłówkami i innymi informacjami. Wspomagane będą przykładowe fragmenty kodu napisane w kilku językach, które opisują sposób wysyłania żądania podczas pisania kodu dla danego interfejsu. Nie trzeba zapominać też o ogólnych kodach błędów występujących w poszczególnych interfejsach API.
To jest ogólne pojęcie o tym, jak zostanie zdefiniowana dokumentacja interfejsu API REST.
Oto harmonogram projektu :
1 sierpnia – 1 września
Poznaj swojego mentora i omów szczegółowo poziom dokumentacji wymaganej w różnych częściach bazy kodu, a także omów szczegółowość dokumentacji niskopoziomowej i ogólnej. Spędzam też czas na poznawaniu bazy kodu i poznawaniu koncepcji, aby lepiej je udokumentować.
Tydzień 1 i 2
Będę aktualizować i rozszerzać przewodnik dla współtwórców. Udoskonalę dokumentację dotyczącą tworzenia kodu źródłowego. Dodam też sekcję poświęconą dokumentowaniu, w której nowi współtwórcy mogą pomagać użytkownikom. Zapoznam się z różną dokumentacją interfejsu API, zacznę od wprowadzenia i dodam do niego uwierzytelnianie.
Tydzień 3–8
Dodam trasy i odpowiedzi interfejsu API wraz z przykładami kodu dla poszczególnych typów interfejsów API (mogą istnieć podobne rodzaje interfejsów API).
Tydzień 9 i 10
Dodaj strukturę dokumentacji API za pomocą linków, tj.powiązany indeks dla długiej dokumentacji API, i podziel go według innych kryteriów, takich jak sekcje kodu, omówienie, parametry, główne punkty końcowe.
Ostatni tydzień
W ostatnim tygodniu posłużę się przygotowaniem ostatecznego raportu o pracy wykonanej w trakcie 12-tygodniowego okresu dokumentacji. Poświęcę też czas na sprawdzenie i sfinalizowanie dokumentacji.