Cara menulis dokumentasi dan ujian API menggunakan spesifikasi Pelan Tindakan API dalam PHP

Dengan perkembangan pesat Internet, penggunaan API Web menjadi semakin biasa Untuk memudahkan pengguna bermula dengan cepat, adalah penting untuk menulis dokumentasi dan ujian API yang baik. API Blueprint ialah spesifikasi dokumen API yang ditulis menggunakan bahasa markup Markdown, yang boleh membantu kami menulis dokumentasi dan ujian API dengan cara yang standard, menjadikan API lebih mudah untuk difahami dan digunakan. Artikel ini akan memperkenalkan cara menggunakan spesifikasi Pelan Tindakan API untuk menulis dokumentasi dan ujian API dalam PHP.

Pasang API Blueprint

Sebelum kita mula, kita perlu memasang API Blueprint terlebih dahulu. Kami boleh memperkenalkan Pelan Tindakan API ke dalam projek PHP melalui Komposer. Jalankan arahan berikut dalam terminal untuk memasang:

composer require apiaryio/php-codex

Tulis dokumentasi API

Tentukan titik akhir

Salah satu ciri utama Pelan Tindakan API ialah ia boleh membantu kami menentukan API titik akhir. Kita boleh menggunakan ## untuk mewakili titik akhir API baharu. Contohnya:

## 用户

以下API端点针对用户进行操作。

### 获取用户列表 [GET /users]

获取用户列表。

+ Response 200 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            [
              {
                "id": 1,
                "username": "user1",
                "name": "User One"
              },
              {
                "id": 2,
                "username": "user2",
                "name": "User Two"
              }
            ]

Perkara di atas mentakrifkan titik akhir pengguna dan titik akhir API untuk mendapatkan senarai pengguna dan mentakrifkan struktur data pulangan, kod ralat dan maklumat lain untuk titik akhir API.

Tentukan parameter permintaan

Kita boleh menggunakan + Parameters untuk menentukan parameter permintaan. Contohnya:

+ Parameters

    + page (int, optional, default: 1) ... 页码
    + per_page (int, optional, default: 10) ... 每页数量

Perkara di atas menunjukkan bahawa titik akhir API menyokong dua parameter permintaan: page dan per_page. Jenis data page ialah integer, pilihan dan nilai lalai ialah 1; jenis data per_page ialah integer, pilihan dan nilai lalai ialah 10.

Tentukan badan permintaan

Kita boleh menggunakan + Request untuk menentukan badan permintaan. Contohnya:

+ Request (application/json)

    {
      "username": "user1",
      "password": "123456"
    }

Perkara di atas menunjukkan bahawa titik akhir API perlu menghantar badan permintaan dalam format JSON, yang mengandungi dua parameter: username dan password.

Tentukan data pemulangan

Kita boleh menggunakan + Response untuk menentukan data pemulangan. Contohnya:

+ Response 200 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            {
              "id": 1,
              "username": "user1",
              "name": "User One"
            }

Di atas menunjukkan bahawa data pulangan titik akhir API adalah dalam format JSON dan mengandungi tiga parameter: id, username dan name.

Tentukan kod ralat

Kita boleh menggunakan + Response untuk menentukan kod ralat. Contohnya:

+ Response 400 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            {
              "error": "请求参数错误"
            }

Perkara di atas bermakna apabila parameter permintaan tidak betul, titik akhir API akan mengembalikan kod status HTTP 400 dan mesej ralat ialah 请求参数错误.

Menulis Ujian API

Satu lagi ciri utama Pelan Tindakan API ialah ia boleh membantu kami menulis ujian API. Kami boleh menggunakan [Dredd](https://dredd.org/en/latest/) untuk menjalankan ujian Pelan Tindakan API.

Pasang Dredd

Laksanakan arahan berikut dalam terminal untuk memasang:

npm install -g dredd

Tulis skrip ujian

Kami boleh mentakrifkan skrip ujian dalam Pelan Tindakan API . Contohnya:

## 用户

以下API端点针对用户进行操作。

### 获取用户列表 [GET /users]

获取用户列表。

+ Request

    + Headers

            Authorization: Token abcdefg

    + Parameters

        + page (int, optional, default: 1) ... 页码
        + per_page (int, optional, default: 10) ... 每页数量

+ Response 200 (application/json)
    + Headers
        Link: ; rel="self"
    + Body

            [
              {
                "id": 1,
                "username": "user1",
                "name": "User One"
              },
              {
                "id": 2,
                "username": "user2",
                "name": "User Two"
              }
            ]

+ Response 401 (application/json)
    + Body

            {
              "error": "您没有访问该接口的权限"
            }

+ Request

    + Headers

            Authorization: Token abcdefg

    + Body

            {
              "username": "user1",
              "password": "123456"
            }

+ Response 200 (application/json)
    + Headers
        Link: <http://example.com>; rel="self"
    + Body

            {
              "id": 1,
              "username": "user1",
              "name": "User One"
            }

+ Response 400 (application/json)
    + Body

            {
              "error": "请求参数错误"
            }

Perkara di atas mentakrifkan titik akhir pengguna dan titik akhir API untuk mendapatkan senarai pengguna dan mentakrifkan skrip ujian dalam Pelan Tindakan API, termasuk menghantar permintaan, respons pengesahan dan kod status HTTP.

Laksanakan skrip ujian

Masukkan direktori di mana API Blueprint terletak di terminal, dan laksanakan arahan berikut untuk ujian API:

dredd api.apib http://localhost:8000

Di atas bermaksud menjalankan ujian skrip Pelan Tindakan API dan menghantar permintaan Pergi ke port tempatan 8000 dan semak sama ada API mematuhi spesifikasi yang dipersetujui.

Kesimpulan

Dengan menggunakan spesifikasi API Blueprint untuk menulis dokumentasi dan ujian API, kami boleh mentakrifkan dengan lebih jelas titik akhir API, parameter permintaan, badan permintaan, data pemulangan, kod ralat dan maklumat lain, menjadikan API lebih jelas Mudah difahami dan digunakan. Pada masa yang sama, menggunakan Dredd untuk ujian API dapat memastikan API mematuhi spesifikasi yang dipersetujui dengan berkesan.

Atas ialah kandungan terperinci Cara menulis dokumentasi dan ujian API menggunakan spesifikasi Pelan Tindakan API dalam PHP. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!