Cara menjana dokumentasi API menggunakan Swagger dalam PHP

Dengan pembangunan aplikasi web yang berterusan, API telah menjadi salah satu piawaian untuk pembangunan aplikasi web moden. Walau bagaimanapun, apabila bilangan dan kerumitan API meningkat, mengekalkan dan mendokumentasikannya menjadi semakin rumit. Untuk menyelesaikan masalah ini, Swagger wujud. Ia adalah alat untuk menjana dokumentasi API, memudahkan pembangun menyelenggara dan mendokumentasikan API, di samping menyediakan dokumentasi visual dan pelbagai ciri lain. Dalam artikel ini, kita akan membincangkan cara menjana dokumentasi API menggunakan Swagger dalam PHP.

Pertama, kita perlu memasang Swagger. Terdapat banyak versi dan pelaksanaan Swagger, tetapi kami akan menggunakan Swagger-php di sini, yang merupakan perpustakaan PHP sumber terbuka yang memudahkan untuk mengintegrasikan Swagger ke dalam kod PHP. Kami boleh memasang Swagger-php dalam projek kami menggunakan Komposer:

composer require zircote/swagger-php

Setelah kami memasang Swagger-php, kami boleh mula menulis spesifikasi Swagger untuk API kami. Spesifikasi Swagger ialah fail JSON atau YAML yang menerangkan semua butiran API, termasuk URL titik akhir, parameter permintaan dan respons, model data dan kod ralat. Dalam Swagger-php, kita boleh menggunakan anotasi PHP untuk menulis spesifikasi. Mari lihat contoh mudah:

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */

Dalam contoh ini, kami telah menggunakan anotasi @OA untuk menulis spesifikasi Swagger. @OA ialah ruang nama dalam perpustakaan Swagger-php yang digunakan untuk mentakrifkan pelbagai jenis elemen Swagger, seperti Info, Dapatkan, Respons dan Parameter. Kami boleh menggunakan anotasi @OAInfo untuk menerangkan maklumat asas API, seperti tajuk dan versi. Dalam anotasi @OAGet, kami mentakrifkan dua titik akhir: /users dan /users/{id}. Kami menghuraikan parameter dan respons permintaan, serta menentukan kod tindak balas kejayaan dan ralat. Ini hanyalah contoh yang sangat kecil, tetapi anda boleh menulis spesifikasi Swagger yang lebih kompleks dengan menggunakan anotasi @OA lain, malah menerangkan pengesahan dan kebenaran API.

Setelah kami menulis spesifikasi Swagger kami, kami boleh menggunakan Swagger-php untuk menukarnya menjadi dokumen visual. Untuk ini, kita boleh menggunakan Swagger-ui, perpustakaan HTML, CSS dan JavaScript untuk memaparkan spesifikasi Swagger. Kita boleh menggunakan pakej Swagger-ui-php dalam PHP untuk menyepadukan Swagger-ui. Kami boleh memasang Swagger-ui-php dalam projek kami menggunakan Komposer:

composer require swagger-api/swagger-ui

Setelah kami memasang Swagger-ui-php, kami boleh menyepadukan Swagger-ui ke dalam aplikasi PHP kami. Kami boleh menambah baris berikut pada kod HTML kami untuk memuatkan Swagger-ui:

<link rel="stylesheet" type="text/css" href="/vendor/swagger-api/swagger-ui/dist/swagger-ui.css">
<div id="swagger-ui"></div>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-bundle.js"></script>
<script src="/vendor/swagger-api/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
<script>
  window.onload = function() {
    // 使用来自后端的Swagger JSON文件构造请求
    SwaggerUIBundle({
      url: "/api/swagger.json",
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset // 用于额外的UI依赖
      ],
      layout: "StandaloneLayout"
    })
  }
</script>

Dalam contoh ini, kami memuatkan fail CSS dan JavaScript Swagger-ui dan menjadikannya dalam fail yang mengandungi "swagger -ui" ID dalam elemen DIV. Kami menggunakan kod JavaScript untuk memuatkan fail JSON Swagger dari bahagian belakang dan menukarnya menjadi dokumen yang cantik menggunakan SwaggerUIBundle.

Akhir sekali, untuk Swagger-ui memuatkan spesifikasi Swagger kami, kami perlu menambah laluan ke aplikasi kami yang mengembalikan fail JSON Swagger.

use OpenApiAnnotations as OA;

$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

// 或者用这种方式

/**
 * @OAServer(url="http://localhost:8000")
 */

/**
 * @OAInfo(title="我的API", version="1.0")
 */

/**
 * @OAGet(
 *     path="/users",
 *     summary="获取所有用户",
 *     @OAResponse(response="200", description="成功响应")
 * )
 */

/**
 * @OAGet(
 *     path="/users/{id}",
 *     summary="获取用户详情",
 *     @OAParameter(name="id", in="path", required=true, description="用户ID"),
 *     @OAResponse(response="200", description="成功响应"),
 *     @OAResponse(response="404", description="用户不存在")
 * )
 */
$app->get('/api/swagger.json', function() use ($app) {
  $openapi = OpenApiscan([__DIR__ . '/routes']);
  return $app->json(json_decode($openapi->toJson()));
});

Dalam contoh ini, kami menggunakan anotasi OpenApi untuk menulis spesifikasi Swagger, tidak seperti contoh sebelumnya. Kami juga menambah laluan untuk mengembalikan fail JSON Swagger. Kami menggunakan fungsi OpenApiscan PHP untuk mengimbas folder laluan kami dan menukar definisi API menjadi objek JSON Swagger, yang kemudiannya ditukar kepada rentetan JSON dan dikembalikan kepada klien.

Dalam artikel ini, kami mempelajari cara menjana dokumentasi API dalam PHP menggunakan Swagger-php dan Swagger-ui. Apabila bilangan dan kerumitan API kami bertambah, Swagger boleh membantu kami mengekalkan dan mendokumentasikannya dengan lebih mudah, sambil menyediakan dokumentasi API visual dan pelbagai ciri lain. Dengan menggunakan anotasi PHP untuk menulis spesifikasi Swagger, kami boleh mengelak daripada menulis dokumentasi secara manual dan menjadikan kod kami lebih jelas dan lebih mudah untuk diselenggara.

Atas ialah kandungan terperinci Cara menjana dokumentasi API menggunakan Swagger dalam PHP. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!