flight php swagger

飞行/招摇捆绑包

Flight 微框架与 Swagger、PHPUnit 和其他有用的实用程序捆绑在一起。旨在通过包括基本项目设置、测试路线和模型以及单元测试模板来帮助启动使用上述工具构建的 API 的开发。

入门

先决条件

本指南假设您当前正在项目中使用（或计划使用）以下技术：

• PHP 7.1+

• 作曲家

• Xdebug（如果您计划使用 PHPUnit，则需要）

安装中

1. 首先，确保您已安装并配置了运行 PHP 7.1 或更高版本的 Web 服务器（例如 Apache）。

2. 使用composer下载项目框架，安装所有必需的依赖项，并运行示例单元测试：

   composer create-project tribeos/flight-php-swagger path/to/project

启用 URL 重写

由于 Flight 依赖于 Apache 2 的mod_rewrite模块才能运行，因此您应该首先通过a2enmod启用它，然后重新启动服务器：

sudo a2enmod rewrite

sudo systemctl restart apache2

之后，您还应该编辑 Apache 的默认配置文件，因为它最初禁止使用.htaccess文件来应用重写规则。配置文件通常位于/etc/apache2/apache2.conf 。在其中，找到引用目录/var/www块，并确保将AllowOverride设置为All并且您Require all granted 。

 <Directory /var/www/>Options Indexes FollowSymLinksAllowOverride AllRequire 全部授予
</目录>

保存更改后，重新启动 Apache 服务器。

如果您拥有或想要拥有多个站点配置，您还可以通过在/etc/apache2/sites-available中编辑所需的配置文件，在每个站点上启用重写规则。您可以参考以下教程以获取更多信息。

注意：上述说明假设您使用的是 Ubuntu 发行版。如果您使用不同的操作系统，请参阅有关启用重写模块的相应教程。

• Windows（WAMP/XAMPP）

• 中央操作系统

安装缺少的 PHP 扩展

该项目及其依赖项需要安装某些 PHP 扩展。您可能缺少的常见扩展可能是以下一些：

问题	解决方案
mbstring	sudo apt install php-mbstring
zip和unzip相关问题	sudo apt install zip unzip php-zip

注意：与前面的 Apache 2 部分一样，这些说明与 Ubuntu 发行版相关。如果使用不同的操作系统，请参阅适当的替代命令。

项目结构

安装完成后，您将在项目中发现以下结构：

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

项目主要组成部分概要：

• app ：主应用程序文件夹

• models ：用于请求/响应的模型

• routes ：API路线的定义

• utils ：应用程序实用程序，例如验证器和记录器

• config ：配置文件

• docs ：Swagger 文档文件

• logs ：日志存储

• tests ：应用程序测试文件夹

• build ：测试生成的任何编译文件（代码覆盖率等）

• src : 测试源文件

• vendor ：所有库和第三方代码的位置

• autoload.php ：加载 Composer 依赖项的引导文件，并包含所有其他项目文件

• index.php ：API入口点

• phpunit.xml ：PHPUnit 测试配置

从事该项目

项目配置

与项目（和 Swagger 文档）相关的所有主要配置都在config/config.php文件内处理。根据您的项目需要更改/添加配置常量。

另一个重要文件是index.php ，它充当 API 入口点。它需要文件autoload.php ，其中包含加载 Composer 依赖项的代码，以及所有其他必要的项目文件。此外，它还启动了 Flight 框架。默认导入的文件都是models 、 routes和utils ，以及项目配置文件( config/config.php )、Swagger-PHP配置文件( docs/swagger.php )和Composer的vendor/autoload.php 。根据您的项目需要更改/添加要导入的文件。

航班

Flight 是一个可扩展且易于使用的 PHP 框架，允许快速创建 RESTful Web API。它使您能够创建详细且实用的 API 端点，并结合中间件功能和覆盖/创建自定义方法的能力。

航班::路线('GET /sample/@value', function($value) {
    Flight::json([ 'sample_value' => $value ]);
});

项目中的所有路由都是通过 Flight 完成的。初始航班设置 ( FlightSetup.php ) 以及所有项目路线均在routes文件夹内处理，并且可以更改以满足您的需求。

Flight 主页 - “学习”区域提供了有关 Flight 的大量使用文档和示例。有关 Flight 框架本身的更多详细信息，您可以访问其 GitHub 存储库。

Swagger-PHP

在routes文件夹中创建路由后，您可以开始为 RESTful API 编写和生成 OpenAPI 文档。

文档写在DocBlocks （又名 PHP 注释块）内，位于相应的路由上方。

 /** * @OAGet( * path="/sample/route", *tags={"sample"}, *summary="示例路线。", * @OAResponse(*response=200, *description="A示例响应。" * ), * security={ * {"api_key": {}} * } * )*/

您可以为每个 RESTful 端点定义路径、标签、简短摘要、参数、默认参数值、请求正文、可用响应、安全身份验证和许多其他选项。

常规 Swagger 配置，例如项目名称、项目作者、API 服务器 URL、规范文件夹等，可以在“Swager 配置常量”区域下的config/config.php中找到和配置。

项目框架附带了docs文件夹，其中包含 Swagger 文档的所有必需文件（PHP 设置文件、HTML 和 CSS）。通过浏览器导航到项目的根路径 ( / ) 即可访问该文档。

有关 Swagger 的一般信息和 OpenAPI 标准的更多信息，请参阅 Swagger 官方主页。 swagger-php 官方主页上提供了有关 PHP 实现的大量使用文档和示例。

项目公用设施

记录器

该项目与 http-logger 捆绑在一起，它是一个 HTTP 请求、响应和错误记录器，它将（默认情况下）将每个传入请求及其相应的响应以制表符分隔值 (TSV) 的形式记录到logs/debug.log中。详细的记录器信息和配置详细信息可以在其 GitHub 页面找到。

记录器需要日志文件的位置（默认情况下通过config/config.php中的常量配置）。此外，为了充分利用记录器的功能，应禁用 Flight 的内部错误处理程序（如果启用，它将在 http-logger 之前捕获某些类型的错误）。

 /* 禁用 FlightPHP 的内部错误记录器。 */Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* 获取并使用记录器 */$logger = HttpLogger::get();$logger->log();

记录器通过routes/FlightSetup.php包含，并在 Flight 中间件函数Flight::after()内进行配置，该函数在每个请求之后运行（因此能够获取适当的响应）。您可以根据您的披露更改记录器功能以及它将监视的路线。

Flight::output()

Flight::output()是一种自定义映射方法，它结合了Flight::json() （JSON 响应输出）和自定义 HTTP Logger 的功能。根据记录器中设置的首选项，通过此方法发出的任何 API 响应都将自动记录。 该方法在routes/FlightSetup.php中定义和配置。

当您想要请求/响应对的日志记录功能而不使用 Flight 中间件进行拦截时，它非常有用。

Flight::output()有两个参数：要发送的实际数据（必需）和响应代码（可选，默认为 200）。

 Flight::output(['sample_message' => '示例响应。'], 301);

Flight::validate()

Flight::validate()使用 Swagger-PHP 分析根据预期的 OpenAPI 模型规范确定传入的请求正文是否有效（包含所有必需的属性）。

所有模型都被声明为类，并且它们的属性被设置为公共。模型在app/models中定义，并遵循以下结构：

 /** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * description="请求正文的示例属性。", * example="示例字符串。" * required=true * ) * @ var 字符串 */public $sample_attribute;
}

在这个具体示例中， description用于简要概述模型的属性， required确定该属性是否是强制的， example为其分配默认值。有关模型架构的更多信息，请参阅 Swagger-PHP 文档。

模型验证器类在utils/Validator.php中声明和定义，并作为自定义映射 Flight 方法包含在routes/FlightSetup.php中。它需要两个参数：要验证请求正文的类，以及请求正文本身。

 Flight::validate(SampleModel::class, Flight::request()->data->getData());

在调用任何其他方法之前，应在 API 路由内部调用该方法。如果模型有效，请求将继续执行。如果模型验证失败，它将输出400 Bad Request响应代码，终止请求。

注意： Flight::validate()取决于Flight::output() ，因此如果您计划从项目中删除自定义输出方法，则应根据需要重写验证器映射方法。

测试项目

该项目包含在 PHPUnit 中，PHPUnit 是一个 PHP 测试框架，除了测试本身之外，还允许生成代码覆盖率。

测试设置

与 PHPUnit 测试相关的所有设置都位于phpunit.xml中。有多个选项可用于设置：

1. 测试文件的位置 在testsuites标签内，可以定义将扫描测试的位置。默认情况下，这是tests/unit 。当定义测试目录（通过directory标签）时，测试文件将在测试执行期间按字母顺序运行。如果需要，我们还可以通过file标签以自定义顺序定义测试文件。

    <测试套件>
        <测试套件名称=“样本测试套件”>
            <directory suffix="Test.php">tests/src/</directory><!-- 默认情况下，测试文件将按字母文件顺序运行。如果要设置特定的执行顺序，请定义单独的测试文件--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
    </测试套件>

2. 测试覆盖率报告的类型 运行测试后可以生成不同类型的测试报告。日志类型在logging标签中定义。默认情况下，所有已编译的测试文件都位于tests/build内。

    <logging><!-- 测试日志类型 --><log type="testdox-html" target="tests/build/testdox.html"/>
        <log type="tap" target="tests/build/report.tap"/>
        <log type="junit" target="tests/build/report.junit.xml"/>
        <log type="coverage-html" target="tests/build/coverage"/>
        <log type="coverage-text" target="tests/build/coverage.txt"/>
        <log type="coverage-clover" target="tests/build/logs/clover.xml"/>
    </记录>

3. 要包含在代码覆盖率中/排除的文件 您还可以选择将哪些文件包含在代码覆盖率报告中（或排除在代码覆盖率报告中）。这是通过whitelist标签内的filter标签完成的。默认情况下，项目的 PHPUnit 设置覆盖app目录中的文件，不包括models和routes （因为这些文件夹不包含可以有效测试代码覆盖率的代码）。您还可以定义自定义包含/排除文件夹和文件。

    <过滤器>
        <whitelist><!-- 用于代码覆盖的文件夹名称--><directory suffix=".php">app/</directory>
            <exclude><!-- 从代码覆盖率中排除的文件/文件夹（没有可测试方法的 PHP 文件）。根据您的项目需求进行编辑。 --><目录后缀=“.php”>app/models</目录>
                <目录后缀=“.php”>应用程序/路由</目录>
            </排除>
        </白名单>
    </过滤器>

编写测试

默认情况下，所有单元测试都应编写在tests/unit目录中。测试文件名应以Test.php结尾，以便 PHPUnit 可以发现它们（如phpunit.xml中定义），例如SampleTest.php 。

测试类被定义为扩展TestCase类，它可以包含各种测试方法。命名测试时，您可以使用以下约定： test + 驼峰式测试的描述（例如testThisIsASampleTest ）。这将允许测试用例名称在测试执行期间转换为描述性句子，为开发人员提供关于测试应该做什么的额外概述。

 /* 测试/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest 扩展 TestCase {public function testThisIsASampleTest() {$this->assertTrue(true);
    }
}

测试执行

要执行所有测试，请在项目根目录中运行vendor/bin/phpunit --testdox 。

 root@ubuntu:/path/to/project$vendor/bin/phpunit --testdox
PHPUnit 7.5.16 由 Sebastian Bergmann 和贡献者编写。

样本
  这是一个测试样本

要仅运行单个测试文件，请提供其路径： vendor/bin/phpunit --testdox tests/unit/SampleTest.php

标志--testdox是可选的，但推荐使用，因为它将根据测试的名称生成有关测试的描述性句子（如上一节所述），从而更容易理解测试内部发生的情况。

执行测试后，会在tests/build/coverage目录下生成代码覆盖率报告，可以通过浏览器打开该路径查看。

作者

• Aldin Kovačević ，框架和文档的初步工作- Aldin-SXR

执照

该骨架已获得麻省理工学院许可。有关详细信息，请参阅许可证文件。

---

工作正在进行中。