flight php swagger ดาวน์โหลด - flight php swagger ดาวน์โหลดซอร์สโค้ด

flight php swagger

หลาม

v0.6.2

ดาวน์โหลด

ชุดเที่ยวบิน/สแวกเกอร์

Flight micro-framework ที่มาพร้อมกับ Swagger, PHPUnit และยูทิลิตี้ที่มีประโยชน์อื่น ๆ ออกแบบมาเพื่อช่วยเริ่มต้นการพัฒนา API ที่สร้างด้วยเครื่องมือดังกล่าวโดยรวมการตั้งค่าโปรเจ็กต์พื้นฐาน เส้นทางและแบบจำลองการทดสอบ รวมถึงเทมเพลตสำหรับการทดสอบหน่วย

เริ่มต้นใช้งาน

ข้อกำหนดเบื้องต้น

คู่มือนี้จะถือว่าคุณกำลังใช้ (หรือวางแผนที่จะใช้) เทคโนโลยีต่อไปนี้ในโครงการของคุณ:

PHP7.1+
ผู้แต่ง
Xdebug (จำเป็นหากคุณวางแผนที่จะใช้ PHPUnit)

กำลังติดตั้ง

ขั้นแรก ตรวจสอบให้แน่ใจว่าคุณได้ติดตั้งและกำหนดค่าเว็บเซิร์ฟเวอร์ที่ทำงานอยู่ (เช่น Apache) ด้วย PHP 7.1 หรือสูงกว่า
ใช้ composer เพื่อดาวน์โหลดโครงร่างโปรเจ็กต์ ติดตั้งการขึ้นต่อกันที่จำเป็นทั้งหมด และรันการทดสอบหน่วยตัวอย่าง:
composer create-project tribeos/flight-php-swagger path/to/project

เปิดใช้งานการเขียน URL ใหม่

เนื่องจาก Flight ขึ้นอยู่กับโมดูล mod_rewrite ของ Apache 2 เพื่อให้ทำงานได้ คุณควรเปิดใช้งานผ่าน a2enmod ก่อนแล้วจึงรีสตาร์ทเซิร์ฟเวอร์:

sudo a2enmod rewrite

sudo systemctl restart apache2

หลังจากนั้น คุณควรแก้ไขไฟล์การกำหนดค่าเริ่มต้นของ Apache เนื่องจากในตอนแรกจะห้ามไม่ให้ใช้ไฟล์ . .htaccess เพื่อใช้กฎการเขียนซ้ำ ไฟล์การกำหนดค่ามักจะอยู่ที่ /etc/apache2/apache2.conf ในนั้น ให้ค้นหาบล็อกที่อ้างอิงถึงไดเร็กทอรี /var/www และตรวจสอบให้แน่ใจว่า AllowOverride ตั้งค่าเป็น All และคุณ Require all granted

 <Directory /var/www/>ดัชนีตัวเลือก FollowSymLinksAllowOverride AllRequire ทั้งหมดได้รับสิทธิ์
</ไดเร็กทอรี>

หลังจากบันทึกการเปลี่ยนแปลงแล้ว ให้รีสตาร์ทเซิร์ฟเวอร์ Apache

ในกรณีที่คุณมีหรือต้องการมีการกำหนดค่าไซต์หลายรายการ คุณยังสามารถเปิดใช้งานกฎการเขียนซ้ำได้สำหรับแต่ละไซต์ โดยแก้ไขไฟล์การกำหนดค่าที่ต้องการใน /etc/apache2/sites-available คุณสามารถดูบทช่วยสอนต่อไปนี้สำหรับข้อมูลเพิ่มเติม

หมายเหตุ : คำแนะนำข้างต้นถือว่าคุณกำลังใช้การแจกจ่าย Ubuntu ในกรณีที่คุณใช้ระบบปฏิบัติการอื่น โปรดดูบทช่วยสอนที่เหมาะสมในการเปิดใช้งานโมดูลการเขียนซ้ำ

วินโดวส์ (WAMP/XAMPP)
CentOS

ติดตั้งส่วนขยาย 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 : ยูทิลิตีของแอปพลิเคชัน เช่น validtors และ loggers

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 รวมถึงไฟล์โปรเจ็กต์ที่จำเป็นอื่นๆ ทั้งหมด นอกจากนี้ยังเริ่มเฟรมเวิร์กการบินอีกด้วย ไฟล์ที่นำเข้าโดยค่าเริ่มต้นคือ models routes และ utils ทั้งหมด เช่นเดียวกับไฟล์การกำหนดค่าโปรเจ็กต์ ( config/config.php ) ไฟล์การกำหนดค่า Swagger-PHP ( docs/swagger.php ) และ vendor/autoload.php เปลี่ยน/เพิ่มไฟล์ที่จะนำเข้าตามความต้องการของโครงการของคุณ

เที่ยวบิน

Flight เป็นเฟรมเวิร์ก PHP ที่ขยายได้และใช้งานง่าย ซึ่งช่วยให้สามารถสร้าง RESTful web API ได้อย่างรวดเร็ว ช่วยให้คุณสร้างตำแหน่งข้อมูล API ที่มีรายละเอียดและใช้งานได้ ควบคู่ไปกับฟังก์ชันมิดเดิลแวร์และความสามารถในการแทนที่/สร้างวิธีการแบบกำหนดเอง

 เที่ยวบิน::route('GET /sample/@value', function($value) {
    เที่ยวบิน::json([ 'sample_value' => $value ]);
-

การกำหนดเส้นทางทั้งหมดในโครงการทำได้ผ่าน Flight การตั้งค่าการบินเริ่มต้น ( FlightSetup.php ) รวมถึงเส้นทางโปรเจ็กต์ทั้งหมดได้รับการจัดการภายในโฟลเดอร์ routes และสามารถเปลี่ยนแปลงได้เพื่อให้เหมาะกับความต้องการของคุณ

เอกสารการใช้งานที่ครอบคลุมและตัวอย่างเกี่ยวกับเที่ยวบินมีอยู่ที่หน้าแรกของเที่ยวบิน - พื้นที่ "เรียนรู้" สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับเฟรมเวิร์ก Flight คุณสามารถเยี่ยมชมพื้นที่เก็บข้อมูล GitHub

Swagger-PHP

หลังจากสร้างเส้นทางในโฟลเดอร์ routes แล้ว คุณสามารถเริ่มเขียนและสร้างเอกสาร OpenAPI สำหรับ RESTful API ของคุณได้

เอกสารประกอบถูกเขียนไว้ภายใน DocBlocks หรือที่รู้จักกันในชื่อบล็อกความคิดเห็น PHP เหนือเส้นทางที่เกี่ยวข้อง

 /** * @OAGet( * path="/sample/route", * tags={"sample"}, * summary="A ตัวอย่างเส้นทาง", * @OAResponse( * response=200, * description="A ตัวอย่างการตอบสนอง" * ), * security={ * {"api_key": {}} * } * )*/

คุณสามารถกำหนดเส้นทาง แท็ก ข้อมูลสรุปโดยย่อ พารามิเตอร์ ค่าพารามิเตอร์เริ่มต้น เนื้อหาของคำขอ การตอบกลับที่มีอยู่ การรับรองความถูกต้องด้านความปลอดภัย และตัวเลือกอื่นๆ มากมายสำหรับตำแหน่งข้อมูล RESTful ทุกจุด

การกำหนดค่าทั่วไปของ Swagger เช่น ชื่อโปรเจ็กต์, ผู้สร้างโปรเจ็กต์, URL เซิร์ฟเวอร์ API, โฟลเดอร์ข้อมูลจำเพาะ ฯลฯ สามารถพบได้และกำหนดค่าใน config/config.php ใต้ส่วน "ค่าคงที่การกำหนดค่า Swager"

โครงร่างโปรเจ็กต์มาพร้อมกับโฟลเดอร์ docs ซึ่งเก็บไฟล์ที่จำเป็นทั้งหมดสำหรับเอกสารประกอบ Swagger (ไฟล์ติดตั้ง PHP, HTML และ CSS) เข้าถึงเอกสารประกอบได้โดยการนำทางไปยังเส้นทางรูท ( / ) ของโปรเจ็กต์ของคุณผ่านเบราว์เซอร์

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ Swagger โดยทั่วไป และมาตรฐาน OpenAPI โปรดดูที่หน้าแรกอย่างเป็นทางการของ Swagger เอกสารการใช้งานที่ครอบคลุมและตัวอย่างเกี่ยวกับการใช้งาน PHP มีอยู่ในหน้าแรกอย่างเป็นทางการของ Swagger-php

สาธารณูปโภคโครงการ

คนตัดไม้

โครงการมาพร้อมกับ http-logger ซึ่งเป็นคำขอ HTTP การตอบสนองและตัวบันทึกข้อผิดพลาดที่จะ (โดยค่าเริ่มต้น) บันทึกทุกคำขอที่เข้ามาและการตอบกลับที่เกี่ยวข้องลงใน logs/debug.log เป็นค่าที่คั่นด้วยแท็บ (TSV) ข้อมูลตัวบันทึกโดยละเอียดและรายละเอียดการกำหนดค่าสามารถดูได้ที่หน้า 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 โดยค่าเริ่มต้น)

 เที่ยวบิน::output(['sample_message' => 'ตัวอย่างการตอบสนอง'], 301);

`Flight::validate()`

Flight::validate() ใช้การวิเคราะห์ Swagger-PHP เพื่อตรวจสอบว่าเนื้อหาคำขอที่ส่งเข้ามานั้นถูกต้องหรือไม่ (ประกอบด้วยแอตทริบิวต์ที่จำเป็นทั้งหมด) ตามข้อกำหนดเฉพาะของโมเดล OpenAPI ที่คาดหวัง

โมเดลทั้งหมดได้รับการประกาศเป็นคลาส และแอตทริบิวต์ของโมเดลนั้นถูกตั้งค่าเป็นสาธารณะ โมเดลถูกกำหนดไว้ใน app/models และเป็นไปตามโครงสร้างนี้:

 /** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * description="Sample คุณลักษณะของเนื้อหาคำขอ", * example="Sample string." * required=true * ) * @ สตริง var */public $sample_attribute;
-

ในตัวอย่างที่เป็นรูปธรรมนี้ description จะใช้เพื่อให้ภาพรวมโดยย่อของคุณสมบัติของโมเดล required จะกำหนดว่าคุณสมบัตินั้นบังคับหรือไม่ และ example จะกำหนดเป็นค่าเริ่มต้น สำหรับข้อมูลเพิ่มเติมเกี่ยวกับโมเดลสกีมา โปรดดูเอกสารประกอบ Swagger-PHP

คลาสตัวตรวจสอบโมเดลได้รับการประกาศและกำหนดไว้ใน utils/Validator.php และรวมเป็นวิธีการบินที่แมปแบบกำหนดเองใน routes/FlightSetup.php ต้องใช้พารามิเตอร์สองตัว: คลาสที่จะใช้ตรวจสอบเนื้อหาคำขอ และตัวคำขอเอง

 เที่ยวบิน::validate(SampleModel::class, เที่ยวบิน::request()->data->getData());

ควรเรียกเมธอดนี้ภายในเส้นทาง API ก่อนที่จะเรียกเมธอดเพิ่มเติมใดๆ หากแบบจำลองถูกต้อง คำขอจะดำเนินการต่อไป ในกรณีที่โมเดลล้มเหลวในการตรวจสอบ โมเดลจะส่งออกรหัสตอบ 400 Bad Request เพื่อยุติคำขอ

หมายเหตุ : Flight::validate() ขึ้นอยู่กับ Flight::output() ดังนั้นหากคุณวางแผนที่จะลบวิธีเอาต์พุตแบบกำหนดเองออกจากโปรเจ็กต์ คุณควรเขียนวิธีการแมปตัวตรวจสอบความถูกต้องใหม่ตามต้องการ

การทดสอบโครงการ

โปรเจ็กต์นี้มาพร้อมกับ 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"/>
        <ประเภทบันทึก = "แตะ" เป้าหมาย = "tests/build/report.tap"/>
        < ประเภทบันทึก = "junit" target = "tests/build/report.junit.xml"/>
        <ประเภทบันทึก = "coverage-html" target = "tests/build/coverage"/>
        <ประเภทบันทึก = "ครอบคลุมข้อความ" target = "tests/build/coverage.txt"/>
        <ประเภทบันทึก = "ความครอบคลุม-clover" target = "tests/build/logs/clover.xml"/>
    </เข้าสู่ระบบ>

ไฟล์ที่จะรวม/แยกออกจากการครอบคลุมโค้ด คุณยังสามารถเลือกไฟล์ที่จะรวมใน (หรือแยกออกจาก) รายงานการครอบคลุมโค้ดได้ ซึ่งทำได้ผ่านแท็ก filter ภายในแท็ก whitelist ตามค่าเริ่มต้น การตั้งค่า PHPUnit ของโปรเจ็กต์จะครอบคลุมไฟล์ภายในไดเร็กทอรี app ยกเว้น models และ routes (เนื่องจากโฟลเดอร์เหล่านี้ไม่มีโค้ดที่สามารถทดสอบความครอบคลุมของโค้ดได้อย่างมีประสิทธิภาพ) คุณยังสามารถกำหนดโฟลเดอร์และไฟล์การรวม/แยกแบบกำหนดเองของคุณได้

    <ตัวกรอง>
        <whitelist><!-- ชื่อของโฟลเดอร์ที่จะใช้สำหรับการครอบคลุมโค้ด --><directory suffix=".php">app/</directory>
            <ไม่รวม><!-- ไฟล์/โฟลเดอร์ที่ไม่รวมอยู่ในการครอบคลุมโค้ด (ไฟล์ PHP ที่ไม่มีวิธีทดสอบ) แก้ไขตามความต้องการโครงการของคุณ --><ส่วนต่อท้ายไดเร็กทอรี=".php">แอป/โมเดล</ไดเร็กทอรี>
                <ส่วนต่อท้ายไดเร็กทอรี=".php">แอป/เส้นทาง</ไดเร็กทอรี>
            </ไม่รวม>
        </ไวท์ลิสต์>
    </ตัวกรอง>

การเขียนแบบทดสอบ

การทดสอบหน่วยทั้งหมดควรเขียนไว้ในไดเร็กทอรีของ tests/unit ตามค่าเริ่มต้น ชื่อไฟล์ทดสอบควรลงท้ายด้วย Test.php เพื่อให้ PHPUnit สามารถค้นพบได้ (ตามที่กำหนดใน phpunit.xml ) เช่น SampleTest.php

คลาสการทดสอบถูกกำหนดให้เป็นการขยายคลาส TestCase และอาจรวมถึงวิธีการทดสอบต่างๆ เมื่อตั้งชื่อการทดสอบ คุณสามารถใช้รูปแบบต่อไปนี้: test + คำอธิบายของการทดสอบในกรณีอูฐ (เช่น testThisIsASampleTest ) ซึ่งจะทำให้ชื่อกรณีทดสอบถูกแปลงเป็นประโยคอธิบายในระหว่างการดำเนินการทดสอบ โดยให้ภาพรวมเพิ่มเติมแก่นักพัฒนาเกี่ยวกับสิ่งที่ควรทำการทดสอบ

 /* tests/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest ขยาย TestCase {ฟังก์ชันสาธารณะ 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 และสามารถดูได้โดยการเปิดพาธนี้ผ่านเบราว์เซอร์