Generar docs de la api rest a partir de metadata declarada con Services API

[matix]

Para crear un servicio tenemos que proveer estrucuturas como la que sigue:

...
'index' => array(
          'help' => 'List all nodes',
          ...
          'args' => array(
            array(
              'name' => 'page',
              'optional' => TRUE,
              'type' => 'int',
              'description' => 'The zero-based index of the page to get, defaults to 0.',
              'default value' => 0,
              'source' => array('param' => 'page'),
            ),
            array(
              'name' => 'fields',
              'optional' => TRUE,
              'type' => 'string',
              'description' => 'The fields to get.',
              'default value' => '*',
              'source' => array('param' => 'fields'),
            ),
            array(
              'name' => 'parameters',
              'optional' => TRUE,
              'type' => 'array',
              'description' => 'Parameters array',
              'default value' => array(),
              'source' => array('param' => 'parameters'),
            ),
            array(
              'name' => 'pagesize',
              'optional' => TRUE,
              'type' => 'int',
              'description' => 'Number of records to get per page.',
              'default value' => variable_get('services_node_index_page_size', 20),
              'source' => array('param' => 'pagesize'),
            ),
          ),

Teniendo toda esa data ya declarada en el codigo tendriamos que encontrar una manera interesante de autogenerar la documentacion de la api. Quizas el mismo modulo Services ya provea una solucion, en cuyo caso solo deberiamos buscar una forma de integrarlo en la wiki del proyecto.

[gerzenstl]

Debe haber algo para generar esa doc. Lo voy a investigar.

[ssebastianj]

Buenas. ¿Vieron estas herramientas para documentar APIs?

• Swagger
• Apiary

[ciegovolador]

frapi podria ser una opcion, es lo mejor que vi, para crear y documentar APIs http://getfrapi.com/

[matix]

Gracias por las sugerencias, las estoy revisando. Estamos buscando más que nada tools que no requieran reescribir la metadata que ya tenemos definida en el modulo services, por ejemplo. En caso de no encontrar algo acorde, estas alternativas estan buenas para tener en cuenta.

[ssebastianj]

O sea, lo que se busca es que la herramienta, a partir de la metadata definida, genere como salida, por ejemplo HTML, para ser visualizado en un navegador ¿correcto?

Por poner un ejemplo, Swagger se integra con Django REST Framework y te genera la documentación de manera automática.

Ahora, desconozco si hay algo así para el mundo PHP.

Si en algún momento necesitan alguna mano más estoy dispuesto a colaborar :smiley: :+1: