8
Ho un server basato su Rails che esegue diversi servizi REST e un'interfaccia utente Web basata su Rails che interagisce con il server utilizzando ActiveResource. Lo stesso server viene utilizzato da altri client (ad es. Mobile). Devo generare documentazione per l'interfaccia REST. Devo fornire l'URL del servizio, l'input/output e la struttura del documento di errore per ciascun servizio.Interfaccia REST self documenting
Idealmente, mi piacerebbe utilizzare un intercettore sul lato server che documenterà il servizio in base al traffico esistente. Mi chiedo se c'è una gemma per farlo.
E 'vero che i servizi REST non hanno bisogno di un WSDL come un web-service classico, ma hanno bisogno di uno schema. Il client deve conoscere l'URL, il metodo HTTP, la struttura del documento di input, la struttura delle risposte e la struttura degli errori per ogni azione. Quello che sto chiedendo è abbastanza simile alla documentazione API che vedi per l'API RESt di YouTube, OPPURE API REST di Twitter. Ad esempio: http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-users%C2%A0show –
Si può sostenere che non è necessario specificare il metodo HTTP per un servizio REST in quanto può essere ingerito dal tipo di operazione. Ma in pratica, se si dispone di un'operazione personalizzata (vale a dire operazione non CRUD) è meglio documentare il metodo HTTP previsto. –
Fatta eccezione per un URI per l'accesso all'applicazione (potrebbero esserci molti URI di ingresso, BTW), tutti gli aspetti menzionati devono essere descritti dalla specifica del tipo di supporto. Il servizio non ha bisogno di alcuna descrizione. Ad esempio, si sviluppano i client AtomPub basati su RFC5023, non basati su alcune descrizioni API. –