flight php swagger
v0.6.2
Micromarco de vuelo incluido con Swagger, PHPUnit y otras utilidades útiles. Diseñado para ayudar a impulsar el desarrollo de API creadas con las herramientas antes mencionadas al incluir la configuración básica del proyecto, rutas y modelos de prueba, así como la plantilla para pruebas unitarias.
Esta guía asume que actualmente está utilizando (o planea utilizar) las siguientes tecnologías en su proyecto:
PHP 7.1+
Compositor
Xdebug (obligatorio si planeas usar PHPUnit)
Primero, asegúrese de haber instalado y configurado un servidor web en ejecución (como Apache) con PHP 7.1 o superior.
Utilice composer para descargar el esqueleto del proyecto, instalar todas las dependencias necesarias y ejecutar las pruebas unitarias de muestra:
composer create-project tribeos/flight-php-swagger path/to/project
Dado que Flight depende del módulo mod_rewrite de Apache 2 para funcionar, primero debes habilitarlo a través de a2enmod y luego reiniciar el servidor:
sudo a2enmod rewrite
sudo systemctl restart apache2
Después, también deberías editar el archivo de configuración predeterminado de Apache, ya que inicialmente prohíbe el uso de un archivo .htaccess para aplicar reglas de reescritura. El archivo de configuración normalmente se encuentra en /etc/apache2/apache2.conf . En él, ubique el bloque que hace referencia al directorio /var/www y asegúrese de que AllowOverride esté configurado en All y que Require all granted .
<Directorio /var/www/>Opciones Índices SeguirSymLinksAllowOverride AllRequerir todo concedido </Directorio>
Después de guardar los cambios, reinicie el servidor Apache.
En caso de que tenga o desee tener varias configuraciones de sitio, también puede habilitar reglas de reescritura por sitio, editando el archivo de configuración deseado en /etc/apache2/sites-available . Puede consultar el siguiente tutorial para obtener más información.
Nota : Las instrucciones antes mencionadas asumen que estás utilizando una distribución de Ubuntu. En caso de que esté utilizando un sistema operativo diferente, consulte el tutorial correspondiente sobre cómo habilitar el módulo de reescritura.
Windows (WAMP/XAMPP)
CentOS
El proyecto y sus dependencias requieren la instalación de ciertas extensiones PHP. Las extensiones comunes que quizás te falten podrían ser algunas de las siguientes:
| Asunto | Solución |
|---|---|
mbstring | sudo apt install php-mbstring |
problemas relacionados con zip y unzip | sudo apt install zip unzip php-zip |
Nota : Al igual que con la sección anterior de Apache 2, estas instrucciones se relacionan con las distribuciones de Ubuntu. Consulte un comando alternativo apropiado si utiliza un sistema operativo diferente.
Una vez finalizada la instalación, encontrarás esta estructura en tu proyecto:
path/to/project ├── app │ ├── models │ │ └── SampleModel.php │ ├── routes │ │ ├── FlightSetup.php │ │ └── SampleRoute.php │ └── utils │ └── Validator.php ├── config │ ├── config.php │ └── config.sample.php ├── docs ├── logs │ └── .htaccess ├── tests │ ├── build │ └── unit │ └── SampleTest.php ├── vendor ├── .gitignore ├── .htaccess ├── autoload.php ├── composer.json ├── composer.lock ├── index.php ├── LICENSE ├── phpunit.xml └── README.md
Resumen de los principales componentes del proyecto:
app : la carpeta principal de la aplicación
models : modelos utilizados para solicitudes/respuestas
routes : definición de rutas API
utils : utilidades de la aplicación, como validadores y registradores.
config : archivo(s) de configuración
docs : archivos de documentación de Swagger
logs : almacenamiento de registros
tests : carpeta de pruebas de la aplicación
build : cualquier archivo compilado resultante de pruebas (cobertura de código, etc.)
src : archivos fuente de prueba
vendor : ubicación de todas las bibliotecas y códigos de terceros
autoload.php : un archivo de arranque que carga las dependencias de Composer e incluye todos los demás archivos del proyecto.
index.php : punto de entrada API
phpunit.xml : configuración de prueba de PHPUnit
Toda la configuración principal relacionada con el proyecto (y la documentación de Swagger) se maneja dentro del archivo config/config.php . Cambie/agregue las constantes de configuración según las necesidades de su proyecto.
Otro archivo importante es index.php , que sirve como punto de entrada a la API. Requiere el archivo autoload.php , que contiene el código para cargar las dependencias de Composer, así como todos los demás archivos de proyecto necesarios. Además, inicia el marco de Vuelo. Los archivos importados por defecto son todos models , routes y utils , así como el archivo de configuración del proyecto ( config/config.php ), el archivo de configuración Swagger-PHP ( docs/swagger.php ) y el vendor/autoload.php del Composer. Cambie/agregue archivos para importar según las necesidades de su proyecto.
Flight es un marco PHP extensible y fácil de usar que permite la creación rápida de API web RESTful. Le permite crear puntos finales API detallados y funcionales, junto con funcionalidades de middleware y la capacidad de anular/crear métodos personalizados.
Vuelo::ruta('GET /muestra/@valor', función($valor) {
Vuelo::json([ 'sample_value' => $valor ]);
}); Todo el enrutamiento del proyecto se realiza mediante Vuelo. La configuración inicial de Flight ( FlightSetup.php ), así como todas las rutas del proyecto, se manejan dentro de la carpeta routes y se pueden cambiar para adaptarlas a sus necesidades.
Amplia documentación de uso y ejemplos sobre Flight están disponibles en la página de inicio de Flight, área "Aprender". Para obtener más detalles sobre el marco Flight en sí, puede visitar su repositorio de GitHub.
Después de crear una ruta en la carpeta routes , puede comenzar a escribir y generar documentación OpenAPI para su API RESTful.
La documentación está escrita dentro de DocBlocks , también conocidos como bloques de comentarios PHP, encima de la ruta correspondiente.
/** * @OAGet( * ruta="/sample/ruta", * etiquetas={"sample"}, * resumen="Una ruta de muestra.", * @OAResponse( * respuesta=200, * descripción="A respuesta de muestra." * ), * seguridad={ * {"api_key": {}} * } * )*/Puede definir la ruta, las etiquetas, el breve resumen, los parámetros, los valores de los parámetros predeterminados, el cuerpo de la solicitud, las respuestas disponibles, la autenticación de seguridad y muchas otras opciones para cada punto final RESTful.
La configuración general de Swagger, como el nombre del proyecto, los autores del proyecto, la URL del servidor API, las carpetas de especificaciones, etc., se pueden encontrar y configurar en config/config.php , en el área "Constantes de configuración de Swager" .
El esqueleto del proyecto viene junto con la carpeta docs , que contiene todos los archivos necesarios para la documentación de Swagger (archivos de configuración PHP, HTML y CSS). Se accede a la documentación navegando a la ruta raíz ( / ) de su proyecto a través de un navegador.
Para obtener más información sobre Swagger en general y el estándar OpenAPI, consulte la página de inicio oficial de Swagger. Amplia documentación de uso y ejemplos sobre la implementación de PHP están disponibles en la página de inicio oficial de swagger-php.
El proyecto viene incluido con http-logger, que es un registrador de solicitudes, respuestas y errores HTTP, que (de forma predeterminada) registrará cada solicitud entrante y su respuesta correspondiente en logs/debug.log , como valores separados por tabulaciones (TSV). La información detallada del registrador y los detalles de configuración se pueden encontrar en su página de GitHub.
El registrador requiere la ubicación del archivo de registro (que de forma predeterminada está configurado mediante una constante en config/config.php ). Además, para utilizar plenamente las capacidades del registrador, el controlador de errores interno de Flight debe estar deshabilitado (si está habilitado, detectará ciertos tipos de errores antes que el registrador http).
/* Desactivar el registrador de errores interno de FlightPHP. */Vuelo::set('vuelo.handle_errors', falso);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* Obtener y usar el registrador */$logger = HttpLogger::get();$logger->log(); El registrador se incluye a través de routes/FlightSetup.php y se configura dentro de la función de middleware Flight Flight::after() , que se ejecuta después de cada solicitud (para que pueda obtener la respuesta adecuada). Puede cambiar las funcionalidades del registrador, así como las rutas que observará, cuando lo indique.
Flight::output() Flight::output() es un método asignado personalizado que combina las funcionalidades de Flight::json() (salida de respuesta JSON) y el registrador HTTP personalizado. Cualquier respuesta de API que se envíe a través de este método se registrará automáticamente, de acuerdo con las preferencias establecidas en el registrador. El método se define y configura en routes/FlightSetup.php .
Es útil cuando desea la funcionalidad de registro para sus pares de solicitud/respuesta sin utilizar el middleware Flight para interceptar.
Flight::output() toma dos parámetros: los datos reales que se enviarán ( requerido ) y el código de respuesta ( opcional , 200 por defecto).
Flight::output(['sample_message' => 'Respuesta de muestra.'], 301);
Flight::validate() Flight::validate() utiliza análisis Swagger-PHP para determinar si el cuerpo de una solicitud pasada es válido (que contiene todos los atributos requeridos) de acuerdo con la especificación esperada del modelo OpenAPI.
Todos los modelos se declaran como clases y sus atributos se establecen como públicos. Los modelos se definen en app/models y siguen esta estructura:
/** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * descripción="Atributo de muestra del cuerpo de la solicitud.", * ejemplo="Cadena de muestra." * require=true * ) * @ var cadena */public $sample_attribute;
} En este ejemplo concreto, description se utiliza para brindar una breve descripción general de la propiedad del modelo, required determina si la propiedad es obligatoria o no y example le asigna un valor predeterminado. Para obtener más información sobre los esquemas modelo, consulte la documentación de Swagger-PHP.
La clase de validador de modelo se declara y define en utils/Validator.php y se incluye como un método de vuelo asignado personalizado en routes/FlightSetup.php . Se necesitan dos parámetros: la clase con la que se validará el cuerpo de la solicitud y el propio cuerpo de la solicitud.
Vuelo::validar(SampleModel::clase, Vuelo::request()->datos->getData());
El método debe llamarse dentro de una ruta API, antes de llamar a cualquier método adicional. Si el modelo es válido, la solicitud continuará con su ejecución. En caso de que el modelo no se valide, generará un código de respuesta 400 Bad Request , finalizando la solicitud.
Nota : Flight::validate() depende de Flight::output() , por lo que si planea eliminar el método de salida personalizado del proyecto, debe reescribir el método asignado del validador según sea necesario.
El proyecto viene incluido con PHPUnit, un framework de pruebas para PHP que, además de probarse a sí mismo, también permite generar cobertura de código.
Toda la configuración relacionada con las pruebas con PHPUnit se encuentra en phpunit.xml . Hay varias opciones disponibles para configurar:
La ubicación de los archivos de prueba Dentro de la etiqueta testsuites , se puede definir la ubicación que se escaneará en busca de pruebas. De forma predeterminada, esto es tests/unit . Cuando se define un directorio de prueba (mediante una etiqueta directory ), los archivos de prueba se ejecutarán en orden alfabético durante la ejecución de la prueba. Si es necesario, también podemos definir los archivos de prueba en un orden personalizado mediante la etiqueta file .
<conjuntos de pruebas>
<testsuite name="conjunto-de-pruebas-de-muestra">
<directory suffix="Test.php">tests/src/</directory><!-- De forma predeterminada, los archivos de prueba se ejecutarán en orden alfabético. Si desea establecer un orden de ejecución específico, defina archivos de prueba individuales--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
</testsuites> Tipos de informes de cobertura de pruebas Se pueden generar diferentes tipos de informes de pruebas después de ejecutar las pruebas. Los tipos de registro se definen en la etiqueta logging . Todos los archivos de prueba compilados se encuentran, de forma predeterminada, dentro tests/build .
<logging><!-- Tipos de registros de prueba --><log type="testdox-html" target="tests/build/testdox.html"/>
<log type="tap" target="pruebas/build/report.tap"/>
<log type="junit" target="pruebas/build/report.junit.xml"/>
<log type="cobertura-html" target="pruebas/compilación/cobertura"/>
<log type="cobertura-texto" target="pruebas/build/coverage.txt"/>
<log type="cobertura-clover" target="pruebas/build/logs/clover.xml"/>
</registro> Archivos que se incluirán/excluirán de la cobertura del código. También puede elegir qué archivos se incluirán (o excluirán) del informe de cobertura del código. Esto se hace a través de la etiqueta filter , dentro de la etiqueta de whitelist . De forma predeterminada, la configuración PHPUnit del proyecto cubre archivos dentro del directorio app , excluyendo models y routes (ya que estas carpetas no contienen código que pueda probarse de manera efectiva para determinar la cobertura del código). También puede definir sus carpetas y archivos personalizados de inclusión/exclusión.
<filtro>
<whitelist><!-- El nombre de la carpeta que se utilizará para la cobertura del código --><directory suffix=".php">app/</directory>
<exclude><!-- Archivos/carpetas excluidos de la cobertura del código (archivos PHP sin métodos comprobables). Edite según las necesidades de su proyecto. --><sufijo de directorio=".php">aplicación/modelos</directorio>
<directorio sufijo=".php">aplicación/rutas</directorio>
</excluir>
</lista blanca>
</filtro> Todas las pruebas unitarias deben escribirse, de forma predeterminada, dentro del directorio tests/unit . Los nombres de los archivos de prueba deben terminar con Test.php , para que sean detectables por PHPUnit (como se define en phpunit.xml ), por ejemplo, SampleTest.php .
Una clase de prueba se define como una extensión de la clase TestCase y puede incluir varios métodos de prueba. Al nombrar las pruebas, puede utilizar la siguiente convención: test + descripción de la prueba en caso camel (por ejemplo, testThisIsASampleTest ). Esto permitirá que el nombre del caso de prueba se convierta en una oración descriptiva durante la ejecución de la prueba, brindando una descripción general adicional al desarrollador sobre lo que debe hacer la prueba.
/* tests/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest extiende TestCase {función pública testThisIsASampleTest() {$this->assertTrue(true);
}
} Para ejecutar todas las pruebas, ejecute vendor/bin/phpunit --testdox dentro del directorio raíz del proyecto.
root@ubuntu:/ruta/al/proyecto$ proveedor/bin/phpunit --testdox PHPUnit 7.5.16 por Sebastian Bergmann y colaboradores. Muestra Esta es una prueba de muestra
Para ejecutar solo un archivo de prueba, proporcione su ruta: vendor/bin/phpunit --testdox tests/unit/SampleTest.php
La bandera --testdox es opcional, pero se recomienda, ya que generará oraciones descriptivas sobre las pruebas basadas en sus nombres (como se discutió en la sección anterior), lo que facilitará la comprensión de lo que sucede dentro de las pruebas.
Después de ejecutar las pruebas, el informe de cobertura del código se genera dentro del directorio tests/build/coverage y se puede ver abriendo esta ruta a través de un navegador.
Aldin Kovačević , trabajo inicial sobre el esqueleto y documentación - Aldin-SXR
El esqueleto tiene la licencia del MIT. Consulte el archivo de LICENCIA para obtener más detalles.
Trabajo en progreso.
