¿Cómo documenta una API REST?

Question

¿Cómo se documenta una API REST? No solo la documentación de cuáles son los recursos, sino realmente cuáles son los datos que se envían en la solicitud y qué datos se envían en la respuesta. No es lo suficientemente útil para saber que algo espera que se envíe XML y devuelve XML; o JASN; o lo que sea. ¿Cómo se documentan los datos que se envían en la solicitud y los datos que se envían en la respuesta?

Lo mejor que he podido encontrar hasta ahora es la herramienta Enunciate donde puedes documentar tu REST API y los elementos de datos. ¿Enunciar es el tipo correcto de herramienta para esto y me estoy perdiendo de otras herramientas que ofrecen esto que debería ver?

Consumidores de mi API REST pueden estar en cualquier lenguaje Python, Java, .NET, etc.

Answer 1

El enfoque que he decidido por mi proyecto es enunciar. Parece ser el estándar de facto para la documentación REST API.

Answer 2

No estoy seguro de si está solicitando una herramienta para ayudarlo con esto, o si está preguntando cuál es la mejor práctica (o ambas).

En cuanto a las mejores prácticas, las mismas cosas se aplican a la documentación de descanso como otra documentación de software - proporcionar una buena página de destino con amplitud (es decir, una lista de sus recursos organizados lógicamente con una propaganda sobre lo que hacen y su URI) con páginas detalladas que explican en profundidad lo que hace cada una, con ejemplos. La API REST de Twitter está muy bien documentada y debería ser un buen modelo.

Twitter API main page

Sample drilldown of one resource

Me encanta esa página desglose. Enumera todos los parámetros que necesita, con una descripción de cada uno. Tiene una barra lateral que enumera los tipos admitidos. Tiene enlaces a páginas relacionadas y otras páginas con la misma etiqueta. Tiene una solicitud y respuesta de muestra.

Answer 3

Puedo estar equivocado, pero parece que quiere algo similar a un esquema WSDL y XML para documentar su API. Sugiero leer la publicación de Joe Gregorio en Do we need WADL? Tiene una buena discusión sobre por qué no utilizar este enfoque para una API REST. Si no desea leer el artículo completo, la idea básica es que la documentación similar a API (es decir, WADL) nunca será suficiente y dará lugar a interfaces frágiles. Otro buen artículo es Does REST need a description language? Tiene muchos buenos enlaces a este tipo de discusión.

Si bien su publicación le da consejos sobre lo que no debe hacer, en realidad no responde la pregunta sobre lo que debe hacer. Lo más importante de REST es la idea de una interfaz uniforme. En otras palabras, GET, PUT, POST y DELETE deberían hacer exactamente lo que crees que deberían hacer. GET recupera una representación del recurso, actualiza PUT, crea POST y elimina DELETE.

La gran pregunta es, entonces, sobre la descripción de sus datos y lo que significa. Siempre puede seguir la ruta de definición de un esquema XML o algo similar y generar documentación a partir del esquema. Personalmente, no encuentro que la documentación generada por la máquina sea tan útil.

En mi humilde opinión, los mejores formatos de datos tienen una extensa documentación legible para personas con ejemplos. Esta es la única forma en que sé cómo describir adecuadamente la semántica. Me gusta el uso de Sphinx para generar este tipo de documentación.

Answer 4

Tengo experiencia usando Enunciate, que es genial, pero realmente no me gustan los clientes que puedes generar con él. Por otro lado, he estado usando swagger en mis últimos proyectos y parece ajustarse a mis necesidades, ¡es realmente genial que debas intentarlo!

ACTUALIZACIÓN 08/03/2016: parece que se puede utilizar para construir enunciar arrogancia docs.
Ver this.