Niedługo zaprojektuję RESTful API, dlatego muszę to opisać, aby umożliwić innym osobom rozpoczęcie wdrażania klientów korzystających z niego.

Rozglądałem się trochę, ale niestety nie znalazłem żadnej znormalizowanej formy opisywania internetowych usług RESTful. To, czego szukam, to coś w rodzaju JavaDoc, chociaż nie musi być generowane z żadnego kodu. Nie mówię też o czymś takim jak WADL, raczej chcę mieć pewną czytelną dla człowieka dokumentację, którą mogę przekazać.

Ze względu na charakter usług internetowych opartych na REST, standaryzacja dokumentacji powinna być dość łatwa. Powinien po prostu wyświetlić dostępne zasoby, odpowiadające im identyfikatory URI, dozwolone metody, typy treści i opis dostępnych akcji. Czy masz jakieś sugestie?

Z góry dziękuję i pozdrawiam