Generar documentación de la API Rest

Navegando hacia

• url_proyecto/rest (ej "http://localhost/toba_referencia/trunk/rest")

se abre la consola Swagger del proyecto. Desde ahí se puede descubrir y probar la API rest del proyecto.

La documentación se genera on-the-fly en base a los annotations del código y el método _get_modelos() de cada clase. Los modelos se utilizan para definir tipos de datos compuestos (Persona, Docente, Recibo, etc) y luego pueden referenciarse desde las anotaciones de cada método para indicar que el método get_list() de la clase recurso_personas retorna una lista de Persona, o para indicar el formato del objeto que espera el método post_list() de la misma.

Anotaciones de los métodos

A continuación se muestra un método anotado de ejemplo y se detallan los tipos de anotaciones y su función:

        /**
         * GET /cursos
         *
         * @param_query $estado string (defecto: A) [A\B] Filtra cursos activos o en baja
         *
         * @param_query $limit integer (defecto: 20) Limitar a esta cantidad de registros
         * @param_query $page integer página
         * @param_query $order string (defecto: +curso) +/-[curso,nombre] Ordena por el/los campos
         *
         * @notes  Los cursos agrupan comisiones y ofrecen consultas convenientes para sistemas externos, como los alumnos que deberían conformar el curso.
         *   Los Filtros se definen como 'condicion;valor' donde 'condicion' puede ser: <br/>
         *     [entre| es_mayor_que| desde| es_mayor_igual_que| es_menor_que| es_menor_igual_que| hasta| es_igual_a| es_distinto_de| contiene| no_contiene|   
         *     comienza_con| termina_con]
         *  
         * @summary       Lista de Cursos
         * @response_type array {"$ref":"Curso"}
         * @errors 200 Exito
         * @errors 400 Error en los parámetros
         */
        function get_list()

Parámetros

Hay 3 tipos de parámetros en una API.

• Identificador de recursos: es el que aparece en la URL de la API. Por ejemplo GET /personas/{id_persona}. El valor del mismo se obtiene del nombre del parámetro en el propio código php. En el caso mencionado, la declaración sería recurso\_personas::get($id\_persona) {}.

• Parámetros de la url (query string): son aquellos especificados luego del "?", por ejemplo GET /personas?param1=abc&param2=xyz.. Para especificarlos en la documentación se usa la anotación @param_query $[nombre] [tipo] [descripcion]

• Parámetros del cuerpo del mensaje (body): son aquellos enviados con formato json en el cuerpo del mensaje. Generalmente son del tipo de algún modelo (objeto) y se representan con la anotación @param_body $[nombre] [Modelo|tipo] [descripcion]

Otros

• @notes se utiliza para documentar comentarios destinados a los consumidores de la API
• @summary una descripción breve que se muestra en el listado global de lo métodos junto a cada uno.
• @response_type el tipo de la respuesta. Puede ser un tipo simple, o si es un arreglo (el formato de Swagger es: array {"$ref":"[ID_Modelo]"} )
• @errors se utiliza para indicar los distintos estados y descripciones de la respuesta. Si denomina errors porque asi lo era en la versión anterior de Swagger pero se utilizan para indicar también los casos de éxito.

Modelos

Para proveer modelos las clases tienen que implementar \rest\lib\modelable (extender de dicha clase es opcional, solo se provee a fines documentativos). La misma tiene solo un metodo _get_modelos() que debe retornar un arreglo de los modelos de la clase. El id de cada uno es la llave del arreglo, y con el mismo se deben referenciar desde las anotaciones.

El modelo se construye con los campos del lado izquierdo, y pueden contener un arreglo con mayor detalle. Por defecto el tipo es string y es todo lo que se necesita para hacer un modelo básico.

Los tipos de datos y campos posibles estan definidos en la documentación de swagger, y la librería solo los convierte a JSON, salvo que estén reservados.

Funcion de mapeo y validación

El modelo puede utilizarse con rest_hydratador para asegurarse que siempre se retorna un objeto que respeta la documentación. Para esto se le entrega la especificación y el recordset de la base de datos que desea validarse. Asimismo se pueden agregar reglas al modelo para mapear y trasnformar los campos.

 rest_hidratador::hidratar([Modelo], $recorset_bd);

Los campos reservados son

• _mapeo: el valor del campo se toma de la columna _mapeo.
• _compuesto: el valor del campo es un subarreglo que se calcula recursivamente con dicha especificacion.
• _id: la fila que no se debe repetir, se usa al agrupar filas con el mismo id, se agrupan segun las columas _agrupado.
• _agrupado: si la columna tiene este atributo se agrupan los valores de la misma entre filas que compartan la columna _id.

Ejemplos

    'Curso' => array(
            'id_curso_externo'=> array('_mapeo' => 'curso'),
            'nombre' => array(),
            'estado' => array('enum' => array('A', 'B')),
            'id_plataforma' => array('_mapeo' => 'sistema'),
            'comisiones' => array('type'=> 'array', 'items'=> array('type'=> 'Comision')),
    ),

    'Comision' => array(
        "comision"          => array('type' => 'integer'),
        "nombre",
        "catedra"    => array('_mapeo' => "nombre_catedra"),

        "modalidades"  => array('_mapeo' => "nombre_modalidad",
                                "type"   => "array", "items" => array("\$ref" => "string")
        ),
        "turno"             => array('_compuesto' =>
                                         array('turno'        => array(),
                                               "nombre" => array('_mapeo' => "nombre_turno"))
        ),
        'ubicacion'         => array('_compuesto' =>
                                         array('ubicacion'        => array(),
                                               'nombre_ubicacion' => array('_mapeo' => "nombre"))
        ),
        'actividad'         => array('_compuesto' => array(
            'codigo' => array('_mapeo' => "codigo_actividad"),
            'nombre' => array('_mapeo' => "nombre_actividad"))
        ),

        'periodo_lectivo'   => array('_compuesto' => array(
            'periodo_lectivo',
            'nombre' => array('_mapeo' => "nombre_periodo"),
        )
        ),
    ),
    );

    'Agrupacion' => array(
    'comision' => array('_id'),
    'horarios' => array('_agrupado', '_compuesto' =>
                        array('dia'    => array('_mapeo' => 'horario_dia'),
                              'inicio' => array('_mapeo' => 'horario_inicio'),
                              'fin'    => array('_mapeo' => 'horario_fin')
                        ),
                    )
    )

Esto mapea algo asi  [comision1; horario1], [comision1; horario2], [comision1; horario3]
a algo asi: [comision1; [horario1, horario2, horario3]]

Cambios en 2.7

En esta versión se migra a 2.7 y se realizan algunos cambios para achicar el salto entre la especificación y las anotaciones. Para migrar realizar lo siguiente:

Se renombra @errors y @response_type a @responses. Además se agrega el tipo por lo que habrá que agregarle uno a los errors.

@responses [estado] [(opcional)|$Modelo] [descripción]

@responses [estado] array [$Modelo] [descripción]