Documentación del API

Un API sin documentación es un bien que nace muerto, ya que no será utilizado nunca. Entonces se requiere que, junto al desarrollo, se prepara una documentación que contenga por lo menos los siguientes elementos:

• Todas las características discutidas hasta este momento, de manera que el uso del API esté bien documentado.
• Una descripción de cada una de las operaciones (GET, POST, PUT, DELETE, PATCH) para cada uno de los recursos existes y que pueden ser accesibles desde el API. En este momento son aproximadamente 100 recursos sobre infraestructura y configuración y 500 recursos directamente relacionados con la información de los módulos de Evolution.
• Una descripción de cada una de las estructuras de datos que retorna el API, para cada uno de los recursos existentes.
• Una lista de los errores que pueden generar el acceso a los recursos
• Ejemplos en diferentes lenguajes de programación, aquellos de mayor uso por la industria (Java, Javascript, Python, C#) para realizar operaciones con el API, incluyendo la configuración del cliente para la autenticación y autorización.

Para lograr estas características, se debe aprovechar el estándar de documentación que utiliza la industria, tal es el caso del OpenAPI v.3, que se va elaborando conforme se va programando cada recurso.

Se utilizará Swagger como mecanismo de generación automática de la documentación del API y estará accesible desde el mismo website en que se aloja el API.

Además para GraphQL, se utilizará Banana Cup Cake, como mecanismo de generación y prueba de consultas (querys) con la sintaxis de GraphQL. Y para generar un diagrama de la gráfica que forman los recursos y sus relaciones se incluye Voyager para GraphQL. En ambos casos estos visores son accesibles desde el mismo website en que se aloja el API.

Advertencia
Poner imágenes y explicar minimamente que proporcionan Swagger, Banana Cup Cake y Voyager.