ホームページ >バックエンド開発 >PHPチュートリアル >PHP で API ブループリント仕様を使用して API ドキュメントとテストを作成する方法
PHP で API ブループリント仕様を使用して API ドキュメントとテストを作成する方法
- WBOYオリジナル
- 2023-06-17 08:50:561597ブラウズ
インターネットの急速な発展に伴い、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 サイトの他の関連記事を参照してください。