W jaki sposób dokumentujesz interfejs API REST?

Question

W jaki sposób dokumentujesz interfejs API REST? Nie tylko dokumentacja zasobów, ale tak naprawdę to, jakie dane są wysyłane w żądaniu i jakie dane są wysyłane w odpowiedzi. Nie wystarczy wiedzieć, że coś oczekuje, że XML zostanie wysłany i zwróci XML; lub JASN; lub cokolwiek. Jak udokumentować dane, które zostaną wysłane w żądaniu i dane przesłane w odpowiedzi?

Najlepsze, co udało mi się znaleźć, to narzędzie Enunciate, w którym można dokumentować interfejs REST API i elementy danych. Czy jest to właściwy rodzaj narzędzia i czy brakuje mi innych narzędzi, które oferują to, na co powinienem zwrócić uwagę?

Konsumenci mojego REST API może być w dowolnym języka Python, Java, .NET, itp

Answer 1

Podejście, że zdecydowałem się na na mój projekt jest ogłosić. Wydaje się być de facto standardem dla dokumentacji REST API.

Answer 2

Nie jestem pewien, czy pytasz o narzędzie, które pomoże ci w tym, czy też pytasz o najlepszą praktykę (lub obie metody).

Co do najlepszych praktyk, to samo odnosi się do dokumentacji REST, podobnie jak innych dokumentacji oprogramowania - zapewnia dobrą szerokość strony docelowej (tj. Listę logicznie uporządkowanych zasobów z informacjami o tym, co robią i ich URI) ze szczegółowymi stronami, które dokładnie wyjaśniają, co robi każdy, z przykładami. REST API na Twitterze jest bardzo dobrze udokumentowany i powinien być dobrym modelem.

Twitter API main page

Sample drilldown of one resource

Uwielbiam tę stronę drążenia. Zawiera listę wszystkich wymaganych parametrów wraz z opisem każdego z nich. Ma pasek boczny z listą obsługiwanych typów. Zawiera linki do stron pokrewnych i innych stron z tym samym tagiem. Ma przykładową prośbę i odpowiedź.

Answer 3

Mogę się mylić, ale wygląda na to, że chcesz coś podobnego do WSDL i schematu XML, aby udokumentować swój interfejs API. Proponuję przeczytać post Joe Gregorio na Do we need WADL? Dobrze się zastanawia, dlaczego nie zastosować tego podejścia do interfejsu API REST. Jeśli nie chcesz czytać całego artykułu, podstawową ideą jest to, że dokumentacja podobna do API (np. WADL) nigdy nie będzie wystarczająca i doprowadzi do kruchego interfejsu. Kolejny dobry artykuł to Does REST need a description language? Ma wiele dobrych linków do tego typu dyskusji.

Podczas gdy jego post zawiera porady na temat tego, czego nie należy robić, nie odpowiada na pytanie, co należy zrobić Największą zaletą REST jest idea jednolitego interfejsu. Innymi słowy, GET, PUT, POST i DELETE powinny robić dokładnie to, co według ciebie powinno robić. GET pobiera reprezentację zasobu, aktualizacje PUT, tworzy POST i usuwa DELETE.

Najważniejsze pytanie dotyczy opisu danych i ich znaczenia. Zawsze można przejść do definicji schematu XML lub czegoś podobnego i wygenerować dokumentację ze schematu. Osobiście nie znajduję dokumentacji generowanej maszynowo, która byłaby przydatna.

W mojej skromnej opinii, najlepsze formaty danych mają obszerną, czytelną dla człowieka dokumentację z przykładami. Tylko w ten sposób wiem, jak właściwie opisać semantykę. Podoba mi się użycie Sphinx do generowania tego typu dokumentacji.

Answer 4

Korzystam z programu Enunciate, który jest świetny, ale nie bardzo podoba mi się klientów, z którymi można go wygenerować. Z drugiej strony używam swagger w moich ostatnich projektach i wydaje mi się, że pasuje do moich potrzeb, jest naprawdę fajnie, powinieneś spróbować!

UPDATE 08/03/2016: Wygląda można użyć ogłosić zbudować Swagger docs.
Zobacz this.