flight php swagger
v0.6.2
Flight 微框架與 Swagger、PHPUnit 和其他有用的實用程式捆綁在一起。旨在透過包含基本專案設定、測試路線和模型以及單元測試範本來幫助啟動使用上述工具建立的 API 的開發。
本指南假設您目前正在專案中使用（或計劃使用）以下技術：
PHP 7.1+
作曲家
Xdebug（如果您打算使用 PHPUnit，則需要）
首先，請確保您已安裝並設定了執行 PHP 7.1 或更高版本的 Web 伺服器（例如 Apache）。
使用composer下載專案框架，安裝所有必要的依賴項，並執行範例單元測試：
composer create-project tribeos/flight-php-swagger path/to/project
由於 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 擴充功能。您可能缺少的常見擴充功能可能是以下一些：
| 問題 | 解決方案 |
|---|---|
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 存儲庫。
在routes資料夾中建立路由後，您可以開始為 RESTful API 編寫和產生 OpenAPI 文件。
文件寫在DocBlocks （又稱 PHP 註解區塊）內，位於對應的路由上方。
/** * @OAGet( * path="/sample/route", *tags={"sample"}, *summary="範例路線。", * @OAResponse(*response=200, *description="A範例回應。您可以為每個 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中。有多個選項可用於設定：
測試檔案的位置 在testsuites標籤內，可以定義將掃描測試的位置。預設情況下，這是tests/unit 。當定義測試目錄（透過directory標籤）時，測試檔案將在測試執行期間按字母順序執行。如果需要，我們也可以透過file標籤以自訂順序定義測試檔案。
<測試套件>
<測試套件名稱=“樣本測試套件”>
<directory suffix="Test.php">tests/src/</directory><!-- 預設情況下，測試檔案將以字母檔案順序運行。如果要設定特定的執行順序，請定義單獨的測試檔案--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
</測試套件>測試覆蓋率報告的類型 執行測試後可以產生不同類型的測試報告。日誌類型在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"/>
</記錄>若要包含在程式碼覆蓋率中/排除的檔案 您也可以選擇要將哪些檔案包含在程式碼覆蓋率報告中（或排除在程式碼覆蓋率報告中）。這是透過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
該骨架已獲得麻省理工學院許可。有關詳細信息，請參閱許可證文件。
工作正在進行中。
