Menggunakan ThinkPHP6 untuk menjana dokumen API secara automatik

Apabila API semakin digunakan secara meluas, penjanaan dokumentasi API secara automatik telah menjadi alat yang sangat diperlukan. Artikel ini akan memperkenalkan cara menggunakan rangka kerja ThinkPHP6 untuk menjana dokumen API secara automatik.

1. Pengenalan kepada rangka kerja ThinkPHP6

ThinkPHP6 ialah rangka kerja sumber terbuka yang cekap, mudah, mudah dan fleksibel yang dibangunkan menggunakan bahasa PHP. Ia menggunakan model pembangunan berorientasikan objek, menyokong seni bina MVC (Model-View-Controller), dan mempunyai fungsi berkuasa seperti penghalaan, caching, pengesahan dan enjin templat.

2. Pasang UI Swagger

Swagger ialah alat penjanaan automatik untuk dokumen API secara automatik dan menyediakan antara muka Web untuk menunjukkan hasil pelaksanaan API. Apabila menggunakan ThinkPHP6 untuk menjana dokumen API secara automatik, kami perlu memasang Swagger terlebih dahulu.

Kami boleh memasang Swagger melalui alat Komposer. Masukkan dalam baris arahan:

composer require zircote/swagger-php

Selepas pemasangan selesai, buat fail konfigurasi Swagger dalam direktori akar projek dan namakannya swagger.php:

<?php
return [
    'swagger' => [
        'api' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'paths' => [
            APP_PATH . '/',
        ],
        'exclude' => [
        ],
        'swagger-ui' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'securityDefinitions' => [
        ],
    ],
];

3. Tentukan dokumen API komen

Untuk membolehkan Swagger mengenal pasti dan menjana dokumentasi API secara automatik, kami perlu menambah ulasan yang sepadan pada kod. ThinkPHP6 menyediakan format ulasan tersuai untuk mentakrifkan dokumentasi API.

Tentukan ulasan dokumen API dalam pengawal:

<?php
declare(strict_types=1);

namespace appcontroller;

class Example
{
    /**
     * @OAGet(
     *      path="/example/index",
     *      operationId="exampleIndex",
     *      tags={"Example"},
     *      summary="示例接口",
     *      description="这是一个示例接口",
     *      @OAResponse(
     *          response=200,
     *          description="操作成功",
     *      ),
     *      @OAResponse(
     *          response=401,
     *          description="未授权",
     *      ),
     *      security={
     *          {"Bearer": {}}
     *      }
     * )
     */
    public function index()
    {
        //接口代码
    }
}

Dalam kod di atas, teg ulasan yang bermula dengan @OA dihuraikan ke dalam format kanonik Swagger. Antaranya, @OAGet mentakrifkan kaedah permintaan API sebagai kaedah Dapatkan mentakrifkan laluan API operationId mentakrifkan teg yang dimiliki oleh ringkasan API; ; perihalan mentakrifkan perihalan terperinci tentang API ;

4. Hasilkan dokumentasi API

Selepas mentakrifkan anotasi dokumentasi API, kami boleh menggunakan Swagger untuk menjana dokumentasi API. Masukkan arahan berikut pada baris arahan:

php think swagger:export --output public/swagger.json

Perintah ini akan menyimpan dokumen API ke fail swagger.json dalam direktori awam.

5. Akses dokumentasi API

Gunakan UI Swagger untuk memaparkan dokumentasi API. Kami boleh menggunakan projek UI Swagger ke pelayan web atau menjalankannya secara tempatan.

Apabila berjalan secara setempat, kita boleh menggunakan arahan berikut untuk memulakan perkhidmatan UI Swagger dengan cepat:

docker run --rm -p 8080:8080 -e SWAGGER_JSON=/data/swagger.json -v /path/to/swagger.json:/data/swagger.json swaggerapi/swagger-ui

Di mana, /path/to/swagger.json ialah laluan mutlak ke swagger.json fail.

Lawati http://localhost:8080 dalam penyemak imbas anda untuk melihat dokumentasi API.

6. Ringkasan

Artikel ini memperkenalkan cara menggunakan rangka kerja ThinkPHP6 dan Swagger untuk menjana dokumen API secara automatik. Menjana dokumen API secara automatik boleh meningkatkan kecekapan pembangunan dan mengurangkan kos penyelenggaraan. Melalui pengenalan artikel ini, saya percaya bahawa pembaca sudah boleh menggunakan rangka kerja ThinkPHP6 dan Swagger dengan mahir untuk merealisasikan penjanaan automatik dokumen API.

Atas ialah kandungan terperinci Menggunakan ThinkPHP6 untuk menjana dokumen API secara automatik. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!