Cześć! 
Od jakiegoś czasu pracuję nad aplikacją która ułatwia proces zarządzania dokumentacją API. Do tej pory używałem apiary, raml, swagger jednak zawsze wymagały dużej kontroli żeby dokumentacja była aktualna. Gdy presja czasu na nowe feature była coraz większa, dokumentacja była pierwszą porzucaną rzeczą (co niestety odbijało się na jakości pracy).
Strona naszego projektu to http://watchdocs.io - jego zadaniem jest generowanie dokumentacji dla zadanej aplikacji z możliwością definicji nowych endpointów w ramach edytora. Ma za zadanie utrzymać dokumentację aktualną jak najmniejszym nakładem pracy developera.
Projekt wykorzystuje middleware który przechwytuje i przesyła strukturę requests/response (JSON) wykonywanych na analizowanej aplikacji. Te dane przesyłane są do naszego serwisu w celu ich analizy i generacji dokumentacji.
Pozwala nam to skonfigurować middleware żeby analizował zapytania wykonywane w ramach testów na continuous integration. Nie jest to jednak wymagane, gdy testów nie ma nasza wtyczka umożliwia podpięcie jej do serwera (np staging) na którym na bierząco analizowane będą faktyczne zapytania.
Aplikacja składa się z czterech części
- middleware (między innymi do RoR) który nagrywa i zabezpiecza zapytania
- aplikacja Sinatra generująca dane do dokumentacji
- aplikacja RoR odpowiadająca za edytor i backend interfejsu uzytkownika
- aplikacja React jako interfejs użytkownika
W chwili obecnej jesteśmy na etapie walidowania pomysłu więc aplikacja jest jeszcze niedostępna publicznie, niemniej jednak można się ze mną skontaktować i będę w stanie pokazać jak aplikacja działa i opowiedzieć więcej o projekcie. Chcę stworzyć narzędzie wygodne dla developera które rozwiąże realne problemy w związku z tym miło by mi było usłyszeć czy spotkaliście się z podobnymi problemami, jak je rozwiązywaliście i czy macie jakieś dodatkowe pomysły? Jak już wspomniałem- na tym etapie walidujemy, tzn aplikacja już teraz pozwala definiować endpointy które nie zostały jeszcze zaimplementowane. Może przez to służyć do tworzenia “kontraktów” między teamem frontend i backend, natomiast plany są ambitne i jak tylko okaże się że jest duże zapotrzebowanie- nowo utworzone endpointy będzie można także wykorzystać jako mock-server.
Dziękuję bardzo za wasz feedback i sugestie co do tego co mogę poprawić!