¿Cuál es la mejor forma de generar la documentación de la API REST?

Estoy buscando una buena manera de generar documentación para una API REST. No necesita conectarse realmente con el código ni nada, pero sería increíble poder escribir la documentación como archivos de texto, señalar la herramienta y generar algunos documentos a partir de ella.¿Cuál es la mejor forma de generar la documentación de la API REST?

¿Alguien por ahí tiene alguna idea? Sé que estoy siendo un poco vago, pero, para ser sincero, no estoy seguro de lo que estoy buscando aquí, principalmente una forma fácil de administrar la documentación.

Fuente

2010-10-14 Kyle Slattery

¿Por qué necesita un archivo de texto con documentación para generar documentación? Quiero decir, realmente, ¿por qué no escribes la documentación en Open Office o algo así y lo guardas como PDF, XML, etc.? Otras herramientas, como doxygen, están destinadas a generar documentación a partir del código fuente y comentarios. –

Lo siento, debería haberlo mencionado: quiero generar archivos HTML a partir de él, pero prefiero no editar HTML para generarlo. Realmente estoy buscando una manera de guardar los documentos en un formato con formato mínimo (usando Markdown o algo similar) y luego transformar eso en un montón de archivos HTML vinculados. –

According to Roy:

"A REST API should spend almost all of its descriptive 
effort in defining the media type(s) used for representing 
resources and driving application state, or in defining 
extended relation names and/or hypertext-enabled mark-up 
for existing standard media types."

auto-descriptivo es una de las ventajas de descanso.

Fuente

2010-10-14 21:49:09 fumanchu

Creo que el punto clave es que realmente no existe una forma estandarizada de documentar un tipo de medio. Si solo hubiera Ciertamente no puede ser generado. –

Aunque no REST, utilicé Sphinx para documentar una API de XML-RPC que consistía en una referencia de API y un tutorial. Sphinx agrega algunas directivas prácticas al ReStructuredText para obtener prácticamente lo que usted solicitó: una colección de archivos de texto con formato ReStructuredText que Sphinx convierte en HTML y PDF, completa con un índice y una tabla de contenidos. Sphinx es fácil de usar y está bien documentado; No creo que sea una exageración decir que puedes empezar con esto en unos diez minutos.

Fuente

2010-10-15 16:28:11 ddbeck

Algunos sistemas RESTful son capaces de escribir su propia API. Eche un vistazo al RESTx, que hace precisamente eso: usted escribe sus componentes y luego crea nuevos servicios web enviando parámetros para esos componentes al servidor (ya sea como JSON o a través de un formulario web). A continuación, obtiene un URI para esos parámetros. Al acceder a él, llama al componente con los parámetros y recupera los resultados.

En cualquier caso, los componentes, así como los servicios web RESTful creados, obtienen una documentación generada automáticamente, que se puede examinar y se puede recuperar en formato HTML o JSON.

Fuente

2010-10-15 16:29:47 jbrendel

¿Cuál es la mejor forma de generar la documentación de la API REST?

Respuesta

Cuestiones relacionadas