PHPバックエンド機能開発においてインターフェースドキュメントを自動生成するにはどうすればよいですか?-PHPチュートリアル-php.cn

PHPバックエンド機能開発においてインターフェースドキュメントを自動生成するにはどうすればよいですか?

王林

リリース： 2023-08-05 11:50:02

オリジナル

1510 人が閲覧しました

PHP バックエンド関数開発でインターフェイスドキュメントを自動生成するにはどうすればよいですか?

現代の Web アプリケーション開発では、インターフェイスドキュメントの作成と保守は非常に重要な部分です。標準化された明確なインターフェイスドキュメントは、開発チームの作業効率を大幅に向上させ、コミュニケーションコストを削減し、また他の開発者がインターフェイスを迅速に理解して使用することを容易にします。

この記事では、PHP バックエンド機能の開発において、Swagger と PHP アノテーションを使用してインターフェイスドキュメントの自動生成を実現する方法を紹介します。

Swagger の概要

Swagger は、RESTful スタイルの Web サービスを定義、構築、使用するためのツールセットです。これには、一連の仕様と、その仕様に基づいてインターフェース文書やクライアントコードなどを自動生成できるツールのセットが含まれます。

Swagger 仕様では、YAML または JSON 形式を使用して、インターフェイスの URL、リクエストメソッド、パラメーター、応答データなどを含むインターフェイスのメタデータを記述します。これらのメタデータを通じて、Swagger はインターフェイスドキュメントを自動的に生成し、開発者がインターフェイスを表示およびテストできる美しい UI インターフェイスを提供できます。

Swagger のインストール

まず、Swagger PHP ライブラリをインストールする必要があります。 PHP 開発では、2 つのライブラリ swagger-php と zircote/swagger-php を使用して、Swagger 仕様のインターフェイスドキュメントを生成できます。

Composer 経由でインストールするzircote/swagger-php:

composer require --dev zircote/swagger-php

ログイン後にコピー

Swagger アノテーションを追加する

次に、PHP コードで Swagger アノテーションを使用して、インターフェースを説明するメタデータ。単純なユーザー登録インターフェイスを例に挙げます。

/**
 * @SWGPost(
 *   path="/user/register",
 *   tags={"user"},
 *   summary="用户注册",
 *   description="用户注册接口",
 *   @SWGParameter(
 *     name="username",
 *     in="formData",
 *     required=true,
 *     type="string",
 *     description="用户名"
 *   ),
 *   @SWGParameter(
 *     name="password",
 *     in="formData",
 *     required=true,
 *     type="string",
 *     format="password",
 *     description="密码"
 *   ),
 *   @SWGResponse(
 *     response=200,
 *     description="注册成功"
 *   )
 * )
 */
public function register(Request $request)
{
    // 注册逻辑代码
}

ログイン後にコピー

上記のコードでは、@SWGPost アノテーションを使用して、インターフェイスの URL とリクエストメソッド @SWGParameter をマークします。 アノテーションはインターフェースのパラメーターを記述するために使用され、@SWGResponse アノテーションはインターフェースの応答データを記述するために使用されます。

インターフェイスドキュメントの生成

Swagger アノテーションを構成した後、コマンドを通じてインターフェイスドキュメントを生成できます。プロジェクトのルートディレクトリで次のコマンドを実行します。

vendor/bin/swagger --output public/swagger.json app/Http/Controllers

ログイン後にコピー

このコマンドは、app/Http/Controllers ディレクトリ内の PHP ファイルをスキャンし、それに基づいて Swagger 仕様インターフェイスドキュメントを生成します。 Swagger 注釈を追加し、public/swagger.json ファイルに保存します。

インターフェイスドキュメントの表示

インターフェイスドキュメントが生成されたら、Swagger UI インターフェイスを開いてインターフェイスを表示およびテストできます。

まず、Swagger UIのHTMLテンプレートファイルをプロジェクトに導入します。次の内容を含む public/swagger/index.html ファイルを作成します。

<!DOCTYPE html>
<html>
<head>
    <title>API 文档</title>
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css">
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
    <script>
        window.onload = function () {
            SwaggerUIBundle({
                url: "/swagger.json",
                dom_id: '#swagger-ui'
            });
        }
    </script>
</body>
</html>

ログイン後にコピー

次に、次の場所で public/swagger/index.html ファイルを開くことができます。ブラウザを使用してインターフェイスのドキュメントを表示します。