PHP で API ブループリント仕様を使用して API ドキュメントとテストを作成する方法-PHPチュートリアル-php.cn

PHP で API ブループリント仕様を使用して API ドキュメントとテストを作成する方法

WBOY

リリース： 2023-06-17 08:58:02

オリジナル

1601 人が閲覧しました

インターネットの急速な発展に伴い、Web API の使用がますます一般的になってきました。ユーザーがすぐに使い始められるようにするには、適切な API ドキュメントとテストを作成することが重要です。 API ブループリントは、Markdown マークアップ言語を使用して記述された API ドキュメント仕様です。これは、標準化された方法で API ドキュメントとテストを作成するのに役立ち、API を理解し、使いやすくします。この記事では、API ブループリント仕様を使用して、PHP で API ドキュメントとテストを作成する方法を紹介します。

API ブループリントのインストール

始める前に、まず API ブループリントをインストールする必要があります。 Composer を通じて API ブループリントを PHP プロジェクトに導入できます。ターミナルで次のコマンドを実行してインストールします。

composer require apiaryio/php-codex

ログイン後にコピー

API ドキュメントの作成

エンドポイントの定義

API ブループリントの主な機能の 1 つは、API の定義に役立つことです。エンドポイント。 ## を使用して、新しい API エンドポイントを表すことができます。例:

## 用户

以下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"
              }
            ]

ログイン後にコピー

上記は、ユーザーリストを取得するためのユーザーエンドポイントと API エンドポイントを定義し、API エンドポイントの戻りデータ構造、エラーコード、その他の情報を定義します。

リクエストパラメータの定義

パラメータを使用してリクエストパラメータを定義できます。例:

+ Parameters

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

ログイン後にコピー

上記は、API エンドポイントが 2 つのリクエストパラメーター page と per_page をサポートしていることを示しています。 page のデータ型は整数でオプションで、デフォルト値は 1 です。per_page のデータ型は整数でオプションで、デフォルト値は 10 です。

リクエスト本文の定義

Request を使用してリクエスト本文を定義できます。例:

+ Request (application/json)

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

ログイン後にコピー

上記は、API エンドポイントが 2 つのパラメーター (username と password) を含むリクエスト本文を JSON 形式で渡す必要があることを示しています。

戻りデータの定義

Response を使用して戻りデータを定義できます。例:

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

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

ログイン後にコピー

上記は、API エンドポイントの戻りデータが JSON 形式であり、3 つのパラメーター (id、username、および name) を含むことを示しています。 。

エラーコードの定義

Response を使用してエラーコードを定義できます。例:

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

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

ログイン後にコピー

上記は、リクエストパラメータが正しくない場合、API エンドポイントは HTTP ステータスコード 400 を返し、エラーメッセージは リクエストパラメータエラー であることを示しています。

API テストの作成

API ブループリントのもう 1 つの主な機能は、API テストの作成に役立つことです。 [Dredd](https://dredd.org/en/latest/) を使用して API ブループリントテストを実行できます。

Dredd をインストールします

ターミナルで次のコマンドを実行してインストールします:

npm install -g dredd

ログイン後にコピー

テストスクリプトを作成します

API ブループリントでテストスクリプトを定義できます。例:

## 用户

以下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": "请求参数错误"
            }

ログイン後にコピー

上記は、ユーザーリストを取得するためのユーザーエンドポイントと API エンドポイントを定義し、リクエストの送信、応答の確認、HTTP ステータスコードを含むテストスクリプトを API ブループリントに定義します。

テストスクリプトを実行します。

ターミナルで API ブループリントが配置されているディレクトリに移動し、次のコマンドを実行して API テストを実行します。

dredd api.apib http://localhost:8000

ログイン後にコピー

上記は、 API ブループリントのテストスクリプトとリクエストの送信ローカルポート 8000 に移動し、API が合意された仕様に準拠しているかどうかを確認します。

結論

API ブループリント仕様を使用して API ドキュメントとテストを作成することで、API エンドポイント、リクエストパラメーター、リクエスト本文、戻りデータ、エラーコード、その他の情報をより明確に定義できます。 API がより明確になり、理解しやすくなり、使いやすくなります。同時に、API テストに Dredd を使用すると、API が合意された仕様に準拠していることを効果的に確認できます。

以上がPHP で API ブループリント仕様を使用して API ドキュメントとテストを作成する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。