En muchos casos hoy en día la documentación de un servicio es crucial para quienes desarrollar un sitio web o aplicación basada en ese servicio y las APIs son fundamentales para la programación.  El gran problema es que la documentación en muchas ocasiones no ayuda a los desarrolladores.

La  Especificación OpenAPI es un estándar abierto para definir y documentar APIs.  Esta especificación permite la generación de documentos.  El problema es que crear una especificación OpenAPI lleva mucho tiempo y esfuerzo, además mantenerla actualizada también lleva su tiempo.

Por suerte IBM ha lanzado una nueva herramienta que facilita la escritura de la documentación de las API, la cual es llamada OpenAPI Comment Parser.

El objetivo de esta herramienta es que los programadores puedan generar la especificación OpenAPI a partir de comentarios en línea con su código. Al estar dentro del código, es mucho más probable que los desarrolladores mantengan actualizada la especificación OpenAPI a medida que se va actualizando el código.

De acuerdo a IBM, este enfoque divide en piezas más pequeñas y por ende más fácil de gestionar de la especificación OpenAPI.  Esto permitirá que los desarrolladores, no tengan que ir a buscar en el archivo gigante de especificaciones de OpenAPI ya que se encuentra allí mismo, en el código que han creado o que han actualizado.

IBM también anunció la introducción de un nuevo formato de especificaciones a medida, que facilita la escritura en los comentarios.   Según la Nicholas Bourdakos de IBM, este nuevo formato reduce en un 50% la cantidad de especificaciones necesarias a ser escritas.

Para probar esta herramienta lo pueden hacer en GitHub.