Cara menggunakan PHP dan Swagger untuk penjanaan dokumentasi API-tutorial php-php.cn

Cara menggunakan PHP dan Swagger untuk penjanaan dokumentasi API

王林

Lepaskan： 2023-05-11 17:52:02

asal

1778 orang telah melayarinya

Dengan perkembangan pesat Internet, API (Antara Muka Pengaturcaraan Aplikasi) telah menjadi cara standard pembangunan aplikasi moden. API merujuk kepada satu set antara muka yang membolehkan aplikasi bertukar data dan fungsi, membolehkan aplikasi berinteraksi antara satu sama lain dengan mudah dan cepat.

Selepas kami mencipta API, untuk memudahkan pembangun lain menggunakan API kami, kami perlu menulis dokumentasi terperinci untuk API. Walau bagaimanapun, menulis dokumentasi API secara manual adalah tugas yang memakan masa dan memakan tenaga, jadi menggunakan alat automatik untuk penjanaan dokumentasi API adalah sangat perlu dan berkesan.

Artikel ini akan memperkenalkan cara menggunakan PHP dan Swagger untuk menjana dokumen API.

1. Apa itu Swagger?

Swagger ialah spesifikasi untuk menerangkan dan mentakrifkan API RESTful. Ia boleh digunakan untuk menjana dokumentasi yang boleh dibaca manusia, serta penjana kod untuk menjana kod sisi klien dan pelayan. Swagger juga boleh digunakan untuk ujian API dan penyahpepijatan.

2. Pemasangan dan konfigurasi Swagger

Untuk menggunakan Swagger untuk menjana dokumen API, anda perlu memasangnya terlebih dahulu. Kami boleh menggunakan Composer untuk memasang Swagger ialah pengurus pergantungan untuk PHP dan boleh memuat turun versi terkini Swagger.

Gunakan arahan berikut untuk memasang Swagger:

composer require "swagger-api/swagger-ui:^3.50"

Salin selepas log masuk

Selepas pemasangan selesai, kita perlu melakukan beberapa konfigurasi untuk Swagger. Cipta fail swagger.php dalam direktori akar projek dan tambah kod berikut:

<?php

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

use OpenApiAnnotations as OA;

$swagger = OpenApiscan('/path/to/your/controllers');

header('Content-Type: application/json');
echo $swagger;

Salin selepas log masuk

Dalam kod di atas, /path/to/your/controllers hendaklah digantikan dengan laluan pengawal anda sendiri. Selain itu, kami juga perlu menambah beberapa konfigurasi pada fail composer.json:

    "config": {
        "platform": {
            "php": "7.4"
        }
    },
    "autoload": {
        "classmap": [
            "app/",
            "database/",
            "routes/",
            "tests/"
        ]
    },
    "require": {
        "php": "^7.4",
        "laravel/framework": "^8.40",
        "tymon/jwt-auth": "^1.0",
        "doctrine/dbal": "^2.13",
        "swagger-api/swagger-ui": "^3.50"
    },
    "require-dev": {
        "facade/ignition": "^2.5",
        "fzaninotto/faker": "^1.9.1",
        "mockery/mockery": "^1.4.2",
        "nunomaduro/collision": "^6.0",
        "phpunit/phpunit": "^9.3.3"
    },

Salin selepas log masuk

3 Gunakan Swagger untuk menjana dokumen API

Selepas memasang dan mengkonfigurasi Swagger, kami boleh mula menggunakannya untuk. menjana dokumentasi API. Kita boleh menggunakan arahan berikut untuk menjana dokumentasi API:

php swagger.php > swagger.json

Salin selepas log masuk

Dalam arahan di atas, swagger.php ialah fail konfigurasi Swagger yang baru dibuat dan swagger.json ialah fail dokumentasi API yang kami hasilkan.

4. Gunakan Swagger UI untuk memaparkan dokumen API

Selepas menjana dokumen API, kami berharap dapat memaparkannya supaya orang lain dapat melihatnya. Anda boleh menggunakan UI Swagger untuk memaparkan dokumentasi API. UI Swagger ialah perpustakaan JavaScript yang digunakan untuk memaparkan maklumat API RESTful dan pelaksanaannya diterangkan oleh Swagger.

Kami boleh menambah kandungan berikut pada fail index.php dalam direktori awam:

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

$swagger = file_get_contents(__DIR__ . '/../swagger.json');
$swaggerData = json_decode($swagger, true);
?>
  <!DOCTYPE html>
  <html>
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.min.css" >
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }
      *, *:before, *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
  <div id="swagger-ui"></div>

  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"> </script>
  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-standalone-preset.js"> </script>
  <script>
      window.onload = function() {
          // Begin Swagger UI call region
          const ui = SwaggerUIBundle({
            url: "<?php echo '/swagger.json'; ?>",
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [
              SwaggerUIBundle.presets.apis,
              SwaggerUIStandalonePreset
            ],
            plugins: [
              SwaggerUIBundle.plugins.DownloadUrl
            ],
            layout: "StandaloneLayout"
          })
          // End Swagger UI call region
          
          window.ui = ui
      }
  </script>
  </body>

  </html>

Salin selepas log masuk

Dalam kod di atas, kami menggunakan perpustakaan JavaScript UI Swagger, yang melaluinya The API dihasilkan dokumentasi dibentangkan dalam bentuk halaman HTML yang cantik.

Sampel halaman yang menunjukkan dokumentasi API ditunjukkan di bawah:

Cara menggunakan PHP dan Swagger untuk penjanaan dokumentasi API

5 Kesimpulan

Menggunakan Swagger boleh mendokumenkan API Menjana dan mengurus dengan mudah. Artikel ini memperkenalkan cara menggunakan PHP dan Swagger untuk menjana dokumen API. Langkah-langkahnya termasuk memasang dan mengkonfigurasi Swagger, menggunakan Swagger untuk menjana dokumen API dan menggunakan UI Swagger untuk memaparkan dokumen API. Saya percaya bahawa pembaca boleh menggunakan Swagger dengan mudah untuk menjana dokumen API mereka sendiri selepas pengenalan dalam artikel ini.

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