Crear documentación de API con Sami y docblocks

Alguna vez ha entrado a https://laravel.com/api/5.3/ y se ha preguntado como es que se genera esa documentación? Si es así le contamos que para eso se utiliza una herramienta llamada Sami.

Como se usa?

Es muy sencillo, lo primero que debe hace es obtener el ejecutable en el root de su proyecto con el siguiente comando:

Ese comando va a descargar un archivo sami.phar en el root del proyecto quien se va a encargar de generar esa documentación a partir de los docblocks en nuestras clases.

Una vez tenemos esto necesitamos crear un archivo de configuración para Sami donde le diremos a donde guardar la documentación, que versiones generar ETC.

En este archivo de configuración le estamos diciendo a sami que genere la documentación de todas las clases de la carpeta app y que lo haga para la rama master y develop, también le estamos diciendo el nombre de la documentación que en nuestro ejemplo es Laraveles JOBS API.

Una vez tenemos estos 2 archivos podemos generar la documentación corriendo el siguiente comando

Esto va a generar un directorio sami/build/sf2 de acuerdo a nuestro archivo de configuración donde se va a guardar todo el HTML generado desde las classes en la carpeta app. Por ejemplo para la siguiente clase

Y listo! tenemos documentación del API (No REST API) de nuestra aplicación. Si quieres ver un ejemplo concreto puedes ingresar a la documentación del API de laravel en https://laravel.com/api/5.3/  o puedes ver la documentación del proyecto Laraveles JOBS que estamos trabajando en hecho en laravel https://api.docs.laravelesjobs.com/master/

Dejo el enlace al repositorio de Github de la documentación del API del proyecto https://github.com/joselfonseca/larvales-jobs-api-docs

Feliz semana!

Comparte este artículo

Entra en la discusión y deja tu comentario

Veces