8
Tengo un servidor basado en Rails que ejecuta varios servicios REST y una interfaz de usuario web basada en Rails que interactúa con el servidor utilizando ActiveResource. El mismo servidor está siendo utilizado por otros clientes (por ejemplo, móvil). Tengo que generar documentación para la interfaz REST. Necesito proporcionar URL de servicio, entrada/salida y estructura de documento de error para cada servicio.Interfaz REST autodocumentada
Idealmente, me gustaría utilizar un interceptor en el lado del servidor que documentará el servicio en función del tráfico existente. Me pregunto si hay una joya para hacer esto.
Es cierto que los servicios REST no necesitan un WSDL como un servicio web clásico, sino que necesitan un esquema. El cliente necesita conocer la URL, el método HTTP, la estructura del documento de entrada, la estructura de respuesta y la estructura de error para cualquier acción. Lo que estoy pidiendo es bastante similar a la documentación de la API que se ve para la API REST de YouTube o la API REST de Twitter. Por ejemplo: http://apiwiki.twitter.com/Twitter-REST-API-Method%3A-users%C2%A0show –
Se puede argumentar que no es necesario especificar el método HTTP para un servicio REST, ya que se puede incluir del tipo de operación. Pero en la práctica, si tiene una operación personalizada (es decir, una operación sin CRUD), es mejor documentar el método HTTP esperado. –
Excepto por un URI para ingresar la aplicación (puede haber muchos URI de entrada, por cierto), todos los aspectos que menciona deben describirse por medio de la especificación de tipo de medio. El servicio no necesita descripción en absoluto. Por ejemplo, desarrolla clientes AtomPub basados en RFC5023, no basados en alguna descripción de API. –