Estructuración de la documentación en línea para una API REST

Estoy construyendo mi primera API Rest que serializa datos en formatos JSON y XML. Me gustaría proporcionar una página de índice a los clientes de API, donde podrían elegir los puntos finales implementados.

¿Qué información debo incluir para que mi API sea más útil y cómo debo organizarla?

Esa es una pregunta muy compleja para una respuesta simple.

Es posible que desee echar un vistazo a los marcos de API existentes, como Swagger Specification ( OpenAPI ), y servicios como apiary.io y apiblueprint.org .

Además, aquí hay un ejemplo de la misma API REST descrita, organizada e incluso diseñada de tres formas diferentes. Puede ser un buen comienzo para que aprenda de las formas comunes existentes.

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

En el nivel más alto, creo que los documentos de API REST de calidad requieren al menos lo siguiente:

• una lista de todos los puntos finales de su API (URL base / relativas)
• tipo de método HTTP GET / POST / ... correspondiente para cada punto final
• solicitud / respuesta tipo MIME (cómo codificar parámetros y analizar respuestas)
• una solicitud / respuesta de muestra, incluidos los encabezados HTTP
• tipo y formato especificados para todos los parámetros, incluidos los de la URL, el cuerpo y los encabezados
• una breve descripción de texto y notas importantes
• un fragmento de código corto que muestra el uso del punto final en lenguajes de programación web populares

También hay muchos marcos de documentos basados ​​en JSON / XML que pueden analizar la definición o el esquema de su API y generar un conjunto conveniente de documentos para usted. Pero la elección de un sistema de generación de documentos depende de su proyecto, idioma, entorno de desarrollo y muchas otras cosas.