Jaki jest najlepszy sposób generowania dokumentacji interfejsu REST API?

Question

Szukam ładny sposób na generowanie dokumentacji dla REST API. Nie musi on łączyć się z kodem ani nic, ale byłoby wspaniale móc pisać dokumentację jako pliki tekstowe, wskazywać na nią narzędzie i generować z niego pewne dokumenty.

Ktoś tam ma jakieś pomysły? Wiem, że jestem trochę niejasny, ale, szczerze mówiąc, nie jestem do końca pewien, czego tu szukam - głównie łatwy sposób na zarządzanie dokumentacją.

Answer 1

According to Roy:

"A REST API should spend almost all of its descriptive 
effort in defining the media type(s) used for representing 
resources and driving application state, or in defining 
extended relation names and/or hypertext-enabled mark-up 
for existing standard media types." 

Self-opisowy jest jedną z korzyści płynących z resztą.

Answer 2

Podczas gdy nie REST, użyłem Sphinx do dokumentowania interfejsu API XML-RPC składającego się z odwołania do interfejsu API i samouczka. Sphinx dodaje kilka przydatnych instrukcji do ReStructuredText, aby uzyskać prawie wszystko, o co prosiłeś: zbiór plików tekstowych w formacie ReStructuredText, które Sphinx zamienia w HTML i PDF, wraz z indeksem i spis treści. Sfinks jest łatwy w użyciu i dobrze udokumentowany; Nie sądzę, że byłoby przesadą stwierdzenie, że możesz zacząć z nim za dziesięć minut.

Answer 3

Niektóre systemy RESTful są w stanie napisać własny interfejs API. Spójrz na numer RESTx, który spełnia następujące funkcje: Piszemy komponenty, a następnie tworzymy nowe usługi sieciowe, wysyłając parametry tych komponentów do serwera (w postaci JSON lub formularza internetowego). Następnie otrzymasz identyfikator URI dla tych parametrów. Dostęp do niego wywołuje komponent z parametrami i pobiera wyniki.

W każdym razie komponenty, jak również utworzone usługi sieciowe RESTful, otrzymują automatycznie wygenerowaną dokumentację, którą można przeglądać i którą można pobrać w formacie HTML lub JSON.