PHP melaksanakan spesifikasi dan amalan API Terbuka sumber terbuka.

Dengan perkembangan Internet, pembangunan aplikasi web telah menjadi topik hangat. Aspek penting ini ialah API (Antara Muka Pengaturcaraan Aplikasi), yang membolehkan aplikasi yang berbeza berkomunikasi dan berinteraksi antara satu sama lain melalui Internet. Dalam reka bentuk API, API terbuka telah menjadi semakin popular kerana ia bukan sahaja menyediakan pembangun dengan fleksibiliti dan keplastikan yang lebih besar, tetapi juga membolehkan inovasi yang lebih luas melalui kerjasama terbuka. Dalam konteks ini, artikel ini akan memperkenalkan spesifikasi Open API dan kaedah praktikal PHP.

Gambaran Keseluruhan Spesifikasi Open API

Kini, banyak pembangun membina aplikasi di Internet melalui API terbuka. Walaupun tujuan API tetap sama, terdapat konvensyen dan spesifikasi yang berbeza semasa mentakrifkan API. Open API ialah satu set spesifikasi dan alatan mesra pembangun yang direka untuk memudahkan pembangunan API dan penjanaan dokumentasi.

Spesifikasi Open API dihoskan oleh Open API Initiative (OAI) Ia adalah satu set dokumen penerangan API yang ditulis dalam JSON atau YAML, yang mentakrifkan operasi, format input/output, pengendalian ralat dan ciri lain. daripada API. Spesifikasi Open API semakin digemari oleh pembangun dan perusahaan kerana ia memberikan banyak faedah, seperti:

• Dokumentasi API Dioptimumkan: Spesifikasi API Terbuka mentakrifkan struktur dan metadata API, yang menyediakan asas untuk dokumentasi API. Binaan ini menyediakan lebih banyak sokongan automasi, menjadikannya lebih mudah untuk dibuat dan diselenggara.
• Reka bentuk API Disatukan: Mengikuti spesifikasi Open API boleh menjadikan reka bentuk API lebih konsisten dan piawai, meningkatkan keserasian di kalangan pembangun.
• Mudah untuk menjana kod pelanggan: Menggunakan spesifikasi Open API, anda boleh menjana pelbagai kod pelanggan dengan mudah, seperti JavaScript, Java, Python, dsb.

Dalam artikel ini, kami akan menggabungkan kaedah khusus untuk melaksanakan spesifikasi Open API dengan PHP.

Amalan

Dalam artikel ini, kami akan menggunakan contoh mudah untuk menggambarkan cara menggunakan spesifikasi Open API pada PHP. Untuk kemudahan demonstrasi, kami akan menggunakan rangka kerja Lumen dan alat PHP Swagger.

Pasang Lumen

Rangka kerja Lumen ialah rangka kerja mikro berdasarkan rangka kerja Laravel dan sangat sesuai untuk membangunkan API. Kami boleh memasang rangka kerja Lumen melalui komposer:

composer create-project --prefer-dist laravel/lumen myapi

Konfigurasikan Swagger PHP

Swagger PHP ialah alat untuk menjana dokumentasi dan kod klien untuk spesifikasi Open API spesifikasi antara muka standard API boleh disepadukan dengan lancar dengan rangka kerja Lumen. Kami boleh memasang kebergantungan PHP Swagger melalui komposer:

composer require zircote/swagger-php

Selepas pemasangan selesai, kami perlu mencipta fail swagger.php untuk mengkonfigurasi Swagger PHP:

<?php
use LaminasConfigFactory;

require_once __DIR__ . '/vendor/autoload.php';

$swagger = OpenApiscan(__DIR__ . '/app/Http/Controllers');

header('Content-Type: application/x-yaml');
echo $swagger->toYaml();

Di sini, kami menggunakan OpenApi sccan kaedah, mengimbas semua pengawal dalam aplikasi, menghasilkan spesifikasi Open API dan menukarnya kepada output format YAML. Pengawal di sini merujuk kepada kelas yang menyimpan kaedah pemprosesan permintaan dan kami akan menunjukkan butiran yang berkaitan dalam kod sampel berikut.

Menulis sampel API

Dalam contoh ini, kami akan melaksanakan aplikasi TODO mudah, yang termasuk operasi API untuk menyenaraikan, mencipta, mengemas kini dan memadam item TODO.

Buat Laluan

Kami mula-mula menentukan laluan API dalam fail laluan. Dalam Lumen, laluan boleh ditakrifkan dalam fail routes/web.php. Dalam contoh ini, kami menambah laluan berikut:

$router->get('/tasks', 'TaskController@index');
$router->post('/tasks', 'TaskController@store');
$router->put('/tasks/{id}', 'TaskController@update');
$router->delete('/tasks/{id}', 'TaskController@destroy');

Di sini, kami mentakrifkan empat laluan, sepadan dengan empat operasi senarai, cipta, kemas kini dan padam. Antaranya, {id} bermaksud parameter perlu dihantar dalam URL, menunjukkan nilai id item TODO yang sepadan.

Buat Pengawal

Kami seterusnya perlu mencipta pengawal untuk mengendalikan permintaan Pengawal ialah kelas yang mengandungi pelbagai kaedah pemprosesan dalam kes ini cipta. app/Http/Controllers/TaskController.php

<?php
namespace AppHttpControllers;

use IlluminateHttpRequest;
use IlluminateDatabaseEloquentModelNotFoundException;
use AppModelsTask;

class TaskController extends Controller
{
    public function index()
    {
        $tasks = Task::all();
        return response()->json($tasks);
    }

    public function store(Request $request)
    {
        $task = new Task;
        $task->title = $request->input('title');
        $task->completed = $request->input('completed');
        $task->save();

        return response()->json($task);
    }

    public function update(Request $request, $id)
    {
        try {
            $task = Task::findOrFail($id);
            $task->title = $request->input('title');
            $task->completed = $request->input('completed');
            $task->save();
            return response()->json($task);
        } catch (ModelNotFoundException $e) {
            return response('Task not found.', 404);
        }
    }

    public function destroy($id)
    {
        try {
            $task = Task::findOrFail($id);
            $task->delete();
            return response(null, 204);
        } catch (ModelNotFoundException $e) {
            return response('Task not found.', 404);
        }
    }
}

Dalam kod di atas, kami menggunakan kaedah

dalam rangka kerja Lumen untuk menyambung ke pangkalan data dan melaksanakan operasi tugasan yang sepadan melalui pelbagai kaedah permintaan HTTP. Model

Perhatikan bahawa dengan sedikit nasib saya tidak menghadapi sebarang masalah semasa membuat pengawal. Jika anda tidak boleh menggunakan pengawal atas sebab tertentu, ia mungkin kerana beberapa sebab pelik yang pelik.

Jana spesifikasi Open API

Kini kami telah mentakrifkan API mudah dan menggunakan spesifikasi Open API. Kami menjalankan arahan berikut untuk mengeluarkan spesifikasi yang dijana ke terminal:

php swagger.php

Output terminal kami akan menjadi dokumen YAML yang mengandungi definisi API kami. Anda boleh menyalin dan menampal ini ke dalam mana-mana editor teks yang anda mahukan.

Seterusnya kita perlu mengakses Swagger UI untuk melihat sama ada spesifikasi Open API dijana:

composer require --dev zircote/swagger-ui-expressive

Selepas memasang Swagger UI, kita boleh menentukan laluan Swagger UI dalam fail

: bootstrap/app.php

<?php

$app->group(['namespace' => 'ZircoteSwaggerExpressiveUi'], function() use ($app) {
    $app->get('/docs', 'Controller::getDocsAction');
});

Selepas fail konfigurasi di atas, antara muka UI Swagger boleh diakses melalui laluan

untuk mengesahkan bahawa definisi API dipaparkan dengan betul. / docs

Ringkasan

Artikel ini memperkenalkan konsep asas spesifikasi Open API dan cara melaksanakan spesifikasi Open API dalam PHP. Dengan menggabungkan rangka kerja Lumen dan alat PHP Swagger, kami boleh mencipta API dengan mudah yang mematuhi spesifikasi dan menjana dokumentasi API dan kod klien yang sepadan, dengan itu meningkatkan kecekapan pembangunan dan kebolehurusan API. Spesifikasi Open API menyediakan reka bentuk API yang sangat mudah dan kaedah penjanaan dokumen, yang boleh meningkatkan kebolehgunaan dan kebolehgunaan API dengan sangat baik dan kondusif untuk kerjasama dan inovasi selanjutnya di kalangan pembangun dan perusahaan.

Atas ialah kandungan terperinci PHP melaksanakan spesifikasi dan amalan API Terbuka sumber terbuka.. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!