unduh flight php swagger - unduh kode sumber flight php swagger

flight php swagger

ular piton

v0.6.2

Unduh

Paket Penerbangan/Swagger

Kerangka mikro penerbangan yang dibundel dengan Swagger, PHPUnit, dan utilitas berguna lainnya. Dirancang untuk membantu memulai pengembangan API yang dibuat dengan alat yang disebutkan di atas dengan menyertakan penyiapan proyek dasar, rute dan model pengujian, serta templat untuk pengujian unit.

Memulai

Prasyarat

Panduan ini mengasumsikan bahwa Anda sedang menggunakan (atau berencana menggunakan) teknologi berikut dalam proyek Anda:

PHP 7.1+
Komposer
Xdebug (diperlukan jika Anda berencana menggunakan PHPUnit)

Menginstal

Pertama, pastikan Anda telah menginstal dan mengkonfigurasi server web yang sedang berjalan (seperti Apache) dengan PHP 7.1 atau lebih tinggi.
Gunakan composer untuk mengunduh kerangka proyek, menginstal semua dependensi yang diperlukan, dan menjalankan pengujian unit sampel:
composer create-project tribeos/flight-php-swagger path/to/project

Aktifkan penulisan ulang URL

Karena Flight bergantung pada modul mod_rewrite Apache 2 agar dapat berfungsi, Anda harus mengaktifkannya terlebih dahulu melalui a2enmod dan kemudian memulai ulang server:

sudo a2enmod rewrite

sudo systemctl restart apache2

Setelah itu, Anda juga harus mengedit file konfigurasi default Apache, karena awalnya melarang penggunaan file .htaccess untuk menerapkan aturan penulisan ulang. File konfigurasi biasanya terletak di /etc/apache2/apache2.conf . Di dalamnya, temukan blok yang merujuk ke direktori /var/www dan pastikan AllowOverride disetel ke All dan Anda Require all granted .

 <Direktori /var/www/>Indeks Opsi FollowSymLinksAllowOverride AllRequire semua diberikan
</Direktori>

Setelah menyimpan perubahan, restart server Apache.

Jika Anda memiliki, atau ingin memiliki, beberapa konfigurasi situs, Anda juga dapat mengaktifkan aturan penulisan ulang per situs, dengan mengedit file konfigurasi yang diinginkan di /etc/apache2/sites-available . Anda dapat merujuk ke tutorial berikut untuk informasi lebih lanjut.

Catatan : Petunjuk di atas mengasumsikan Anda menggunakan distribusi Ubuntu. Jika Anda menggunakan sistem operasi yang berbeda, silakan lihat tutorial yang sesuai tentang cara mengaktifkan modul penulisan ulang.

Windows (WAMP/XAMPP)
CentOS

Instal ekstensi PHP yang hilang

Proyek dan dependensinya memerlukan instalasi ekstensi PHP tertentu. Ekstensi umum yang mungkin Anda lewatkan mungkin adalah beberapa hal berikut:

Masalah	Larutan
`mbstring`	`sudo apt install php-mbstring`
masalah terkait `zip` dan `unzip`	`sudo apt install zip unzip php-zip`

Catatan : Seperti bagian Apache 2 sebelumnya, instruksi ini berhubungan dengan distribusi Ubuntu. Lihat perintah alternatif yang sesuai jika menggunakan sistem operasi yang berbeda.

Struktur proyek

Setelah instalasi selesai, Anda akan menemukan struktur ini di proyek Anda:

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

Ikhtisar komponen proyek utama:

app : folder aplikasi utama

models : model yang digunakan untuk permintaan/tanggapan
routes : definisi rute API
utils : utilitas aplikasi, seperti validtor dan logger

config : file konfigurasi
docs : File dokumentasi angkuh
logs : penyimpanan log
tests : folder tes aplikasi

build : semua file yang dikompilasi yang menghasilkan tes formulir (cakupan kode, dll.)
src : menguji file sumber

vendor : lokasi semua perpustakaan dan kode pihak ketiga
autoload.php : File bootstrapping yang memuat dependensi Komposer, dan menyertakan semua file proyek lainnya
index.php : titik masuk API
phpunit.xml : Konfigurasi pengujian PHPUnit

Bekerja pada proyek

Konfigurasi proyek

Semua konfigurasi utama yang terkait dengan proyek (dan dokumentasi Swagger) ditangani di dalam file config/config.php . Ubah/tambahkan konstanta konfigurasi sesuai dengan kebutuhan proyek Anda.

File penting lainnya adalah index.php , yang berfungsi sebagai titik masuk API. Ini memerlukan file autoload.php , yang berisi kode untuk memuat dependensi Komposer, serta semua file proyek lain yang diperlukan. Selain itu, ini memulai kerangka Penerbangan. File yang diimpor secara default adalah semua models , routes dan utils , serta file konfigurasi proyek ( config/config.php ), file konfigurasi Swagger-PHP ( docs/swagger.php ) dan vendor/autoload.php Komposer. Ubah/tambahkan file yang akan diimpor sesuai kebutuhan proyek Anda.

Penerbangan

Flight adalah kerangka kerja PHP yang dapat diperluas dan mudah digunakan yang memungkinkan pembuatan API web RESTful dengan cepat. Ini memungkinkan Anda membuat titik akhir API yang terperinci dan fungsional, ditambah dengan fungsionalitas middleware dan kemampuan untuk mengganti/membuat metode khusus.

 Penerbangan::route('GET /sample/@value', function($value) {
    Penerbangan::json([ 'nilai_sampel' => $nilai ]);
});

Semua perutean dalam proyek dilakukan melalui Penerbangan. Pengaturan Penerbangan awal ( FlightSetup.php ), serta semua rute proyek ditangani di dalam folder routes , dan dapat diubah sesuai kebutuhan Anda.

Dokumentasi penggunaan ekstensif dan contoh tentang Penerbangan tersedia di beranda Penerbangan - area "Pelajari". Untuk detail lebih lanjut tentang kerangka Flight itu sendiri, Anda dapat mengunjungi repositori GitHub-nya.

Kesombongan-PHP

Setelah membuat rute di folder routes , Anda dapat mulai menulis dan membuat dokumentasi OpenAPI untuk RESTful API Anda.

Dokumentasi ditulis di dalam DocBlocks , alias blok komentar PHP, di atas rute yang sesuai.

 /** * @OAGet( * path="/sample/route", * tag={"sample"}, * ringkasan="Contoh rute.", * @OAResponse( * respon=200, * deskripsi="A contoh tanggapan." * ), * keamanan={ * {"api_key": {}} * } * )*/

Anda dapat menentukan jalur, tag, ringkasan singkat, parameter, nilai parameter default, isi permintaan, respons yang tersedia, autentikasi keamanan, dan banyak opsi lainnya untuk setiap titik akhir RESTful.

Konfigurasi umum Swagger, seperti nama proyek, penulis proyek, URL server API, folder spesifikasi, dll. dapat ditemukan dan dikonfigurasi di config/config.php , di bawah area "Konstanta konfigurasi Swager" .

Kerangka proyek dilengkapi dengan folder docs , yang menyimpan semua file yang diperlukan untuk dokumentasi Swagger (file setup PHP, HTML dan CSS). Dokumentasi diakses dengan menavigasi ke rute root ( / ) proyek Anda melalui browser.

Untuk informasi lebih lanjut tentang Swagger secara umum, dan standar OpenAPI, lihat beranda resmi Swagger. Dokumentasi penggunaan yang luas dan contoh mengenai implementasi PHP tersedia di beranda resmi swagger-php.

Utilitas proyek

penebang

Proyek ini dibundel dengan http-logger, yang merupakan permintaan HTTP, respons, dan pencatat kesalahan, yang (secara default) akan mencatat setiap permintaan masuk dan respons terkait ke logs/debug.log , sebagai nilai yang dipisahkan tab (TSV). Informasi logger terperinci dan detail konfigurasi dapat ditemukan di halaman GitHub-nya.

Logger memerlukan lokasi file log (yang secara default dikonfigurasi melalui konstanta di config/config.php ). Selain itu, untuk memanfaatkan sepenuhnya kemampuan logger, pengendali kesalahan internal Flight harus dinonaktifkan (jika diaktifkan, ia akan menangkap jenis kesalahan tertentu sebelum http-logger).

 /* Hapus pencatat kesalahan internal FlightPHP. */Penerbangan::set('penerbangan.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* Dapatkan dan gunakan logger */$logger = HttpLogger::get();$logger->log();

Logger disertakan melalui routes/FlightSetup.php , dan dikonfigurasikan di dalam fungsi middleware Flight Flight::after() , yang berjalan setelah setiap permintaan (sehingga dapat mengambil respons yang sesuai). Anda dapat mengubah fungsi logger, serta rute yang akan dipantau, sesuai pengungkapan Anda.

`Flight::output()`

Flight::output() adalah metode pemetaan khusus yang menggabungkan fungsi Flight::json() (output respons JSON), dan HTTP Logger khusus. Respons API apa pun yang dikirim melalui metode ini akan dicatat secara otomatis, sesuai dengan preferensi yang ditetapkan di logger. Metode ini didefinisikan dan dikonfigurasi di routes/FlightSetup.php .

Ini berguna ketika Anda menginginkan fungsionalitas logging untuk pasangan permintaan/respons Anda tanpa menggunakan middleware Penerbangan untuk mencegat.

Flight::output() mengambil dua parameter: data aktual yang akan dikirim ( diperlukan ), dan kode respons ( opsional , 200 secara default).

 Flight::output(['sample_message' => 'Contoh tanggapan.'], 301);

`Flight::validate()`

Flight::validate() menggunakan analitik Swagger-PHP untuk menentukan apakah isi permintaan yang diteruskan valid (berisi semua atribut yang diperlukan) sesuai dengan spesifikasi model OpenAPI yang diharapkan.

Semua model dideklarasikan sebagai kelas, dan atributnya disetel ke publik. Model didefinisikan dalam app/models , dan mengikuti struktur ini:

 /** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * deskripsi="Contoh atribut dari isi permintaan.", * example="Contoh string." * diperlukan=true * ) * @ var string */publik $sample_attribute;
}

Dalam contoh nyata ini, description digunakan untuk memberikan gambaran singkat tentang properti model, required menentukan apakah properti tersebut wajib atau tidak, dan example memberikan nilai default. Untuk informasi selengkapnya tentang skema model, lihat dokumentasi Swagger-PHP.

Kelas validator model dideklarasikan dan didefinisikan di utils/Validator.php , dan disertakan sebagai metode Flight yang dipetakan khusus di routes/FlightSetup.php . Dibutuhkan dua parameter: kelas yang akan digunakan untuk memvalidasi isi permintaan, dan isi permintaan itu sendiri.

 Penerbangan::validasi(SampleModel::kelas, Penerbangan::permintaan()->data->getData());

Metode ini harus dipanggil di dalam rute API, sebelum metode tambahan apa pun dipanggil. Jika model valid, permintaan akan dilanjutkan dengan eksekusi. Jika model gagal memvalidasi, model akan mengeluarkan kode respons 400 Bad Request , yang menghentikan permintaan.

Catatan : Flight::validate() bergantung pada Flight::output() , jadi jika Anda berencana menghapus metode keluaran khusus dari proyek, Anda harus menulis ulang metode yang dipetakan validator sesuai kebutuhan.

Menguji proyek

Proyek ini disertakan dengan PHPUnit, kerangka pengujian untuk PHP yang, selain menguji dirinya sendiri, juga memungkinkan pembuatan cakupan kode.

Pengaturan pengujian

Semua pengaturan yang terkait dengan pengujian dengan PHPUnit terletak di phpunit.xml . Ada beberapa opsi yang tersedia untuk pengaturan:

Lokasi file pengujian Di dalam tag testsuites , lokasi yang akan dipindai untuk pengujian dapat ditentukan. Secara default, ini adalah tests/unit . Ketika direktori pengujian ditentukan (melalui tag directory ), file pengujian akan dijalankan dalam urutan abjad selama eksekusi pengujian. Jika diperlukan, kita juga dapat menentukan file pengujian dalam urutan khusus melalui tag file .

    <testsuite>
        <nama testsuite = "sampel-test-suite">
            <directory suffix="Test.php">tests/src/</directory><!-- Secara default, file pengujian akan dijalankan dalam urutan file berdasarkan abjad. Jika Anda ingin menetapkan urutan eksekusi tertentu, tentukan masing-masing file pengujian--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
    </testsuite>

Jenis laporan cakupan pengujian Berbagai jenis laporan pengujian dapat dibuat setelah pengujian dijalankan. Jenis log ditentukan dalam tag logging . Semua file tes yang dikompilasi, secara default, terletak di dalam tests/build .

    <logging><!-- Jenis log pengujian --><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"/>
    </pencatatan>

File yang akan disertakan/dikecualikan dari cakupan kode Anda juga dapat memilih file mana yang akan disertakan dalam (atau dikecualikan dari) laporan cakupan kode. Itu dilakukan melalui tag filter , di dalam tag whitelist . Secara default, pengaturan PHPUnit proyek mencakup file dalam direktori app , tidak termasuk models dan routes (karena folder ini tidak berisi kode yang dapat diuji cakupan kodenya secara efektif). Anda juga dapat menentukan folder dan file penyertaan/pengecualian khusus Anda.

    <filter>
        <whitelist><!-- Nama folder yang akan digunakan untuk cakupan kode --><directory suffix=".php">app/</directory>
            <exclude><!-- File/folder dikecualikan dari cakupan kode (file PHP tanpa metode yang dapat diuji). Edit sesuai dengan kebutuhan proyek Anda. --><directory suffix=".php">aplikasi/model</directory>
                <akhiran direktori=".php">aplikasi/rute</direktori>
            </kecualikan>
        </daftar putih>
    </filter>

Menulis tes

Semua pengujian unit harus, secara default, ditulis di dalam direktori tests/unit . Nama file pengujian harus diakhiri dengan Test.php , sehingga dapat ditemukan oleh PHPUnit (seperti yang didefinisikan dalam phpunit.xml ), misalnya SampleTest.php .

Kelas pengujian didefinisikan sebagai perluasan kelas TestCase , dan dapat mencakup berbagai metode pengujian. Saat memberi nama pengujian, Anda dapat menggunakan konvensi berikut: test + deskripsi pengujian dalam huruf unta (misalnya testThisIsASampleTest ). Ini akan memungkinkan nama kasus pengujian diubah menjadi kalimat deskriptif selama pelaksanaan pengujian, memberikan gambaran tambahan kepada pengembang tentang apa yang harus dilakukan pengujian.

 /* tes/unit/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;kelas SampleTest memperluas TestCase {fungsi publik testThisIsASampleTest() {$this->assertTrue(true);
    }
}

Eksekusi tes

Untuk menjalankan semua pengujian, jalankan vendor/bin/phpunit --testdox di dalam direktori root proyek.

 root@ubuntu:/path/ke/project$ vendor/bin/phpunit --testdox
PHPUnit 7.5.16 oleh Sebastian Bergmann dan kontributor.

Mencicipi
  Ini adalah tes sampel

Untuk menjalankan hanya satu file pengujian, berikan jalurnya: vendor/bin/phpunit --testdox tests/unit/SampleTest.php

Tanda --testdox bersifat opsional, namun disarankan, karena akan menghasilkan kalimat deskriptif tentang pengujian berdasarkan namanya (seperti yang dibahas pada bagian di atas), sehingga memudahkan untuk memahami apa yang terjadi di dalam pengujian.

Setelah menjalankan pengujian, laporan cakupan kode dihasilkan di dalam direktori tests/build/coverage , dan dapat dilihat dengan membuka jalur ini melalui browser.