PHP と Swagger を使用して API ドキュメントを生成する方法-PHPチュートリアル-php.cn

PHP と Swagger を使用して API ドキュメントを生成する方法

王林

リリース： 2023-05-11 17:52:02

オリジナル

1750 人が閲覧しました

インターネットの急速な発展に伴い、API (アプリケーションプログラミングインターフェイス) は現代のアプリケーション開発の標準的な方法になりました。 API は、アプリケーションがデータと機能を交換できるようにする一連のインターフェイスを指し、アプリケーションが相互に便利かつ迅速に対話できるようにします。

API を作成した後、他の開発者が API を使用しやすくするために、API の詳細なドキュメントを作成する必要があります。ただし、API ドキュメントを手動で作成するのは時間と労力がかかる作業であるため、API ドキュメントの生成に自動ツールを使用することは非常に必要かつ効果的です。

この記事では、PHP と Swagger を使用して API ドキュメントを生成する方法を紹介します。

1.Swagger とは何ですか?

Swagger は、RESTful API を記述および定義するための仕様です。これは、人間が判読できるドキュメントを生成したり、クライアント側およびサーバー側のコードを生成するコードジェネレーターを生成したりするために使用できます。 Swagger は、API のテストとデバッグにも使用できます。

2. Swagger のインストールと構成

Swagger を使用して API ドキュメントを生成するには、まず Swagger をインストールする必要があります。 Composer を使用して Swagger をインストールできます。Composer は PHP の依存関係マネージャーであり、Swagger の最新バージョンをダウンロードできます。

次のコマンドを使用して Swagger をインストールします:

composer require "swagger-api/swagger-ui:^3.50"

ログイン後にコピー

インストールが完了したら、Swagger の構成をいくつか実行する必要があります。プロジェクトのルートディレクトリに swagger.php ファイルを作成し、次のコードを追加します。

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use OpenApiAnnotations as OA;

$swagger = OpenApiscan('/path/to/your/controllers');

header('Content-Type: application/json');
echo $swagger;

ログイン後にコピー

上記のコードでは、/path/to/your/controllers を独自のコントローラーパスに置き換える必要があります。さらに、composer.json ファイルにいくつかの設定を追加する必要もあります:

    "config": {
        "platform": {
            "php": "7.4"
        }
    },
    "autoload": {
        "classmap": [
            "app/",
            "database/",
            "routes/",
            "tests/"
        ]
    },
    "require": {
        "php": "^7.4",
        "laravel/framework": "^8.40",
        "tymon/jwt-auth": "^1.0",
        "doctrine/dbal": "^2.13",
        "swagger-api/swagger-ui": "^3.50"
    },
    "require-dev": {
        "facade/ignition": "^2.5",
        "fzaninotto/faker": "^1.9.1",
        "mockery/mockery": "^1.4.2",
        "nunomaduro/collision": "^6.0",
        "phpunit/phpunit": "^9.3.3"
    },

ログイン後にコピー

3. Swagger を使用して API ドキュメントを生成する

Swagger をインストールして設定したら、次の目的で Swagger を使用し始めることができます。 API ドキュメントを生成します。次のコマンドを使用して API ドキュメントを生成できます。

php swagger.php > swagger.json

ログイン後にコピー

上記のコマンドでは、swagger.php は作成したばかりの Swagger 構成ファイルで、swagger.json は生成した API ドキュメントファイルです。

4. Swagger UI を使用して API ドキュメントを表示します

API ドキュメントを生成した後、他の人が閲覧できるように表示したいと考えています。 Swagger UI を使用して API ドキュメントを表示できます。 Swagger UI は、RESTful API 情報と Swagger によって記述されたその実装を表示するために使用される JavaScript ライブラリです。

次のコンテンツをパブリックディレクトリのindex.php ファイルに追加できます:

require_once(__DIR__ . '/../vendor/autoload.php');

$swagger = file_get_contents(__DIR__ . '/../swagger.json');
$swaggerData = json_decode($swagger, true);
?>
  <!DOCTYPE html>
  <html>
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.min.css" >
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }
      *, *:before, *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
  <div id="swagger-ui"></div>

  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"> </script>
  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-standalone-preset.js"> </script>
  <script>
      window.onload = function() {
          // Begin Swagger UI call region
          const ui = SwaggerUIBundle({
            url: "<?php echo '/swagger.json'; ?>",
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [
              SwaggerUIBundle.presets.apis,
              SwaggerUIStandalonePreset
            ],
            plugins: [
              SwaggerUIBundle.plugins.DownloadUrl
            ],
            layout: "StandaloneLayout"
          })
          // End Swagger UI call region
          
          window.ui = ui
      }
  </script>
  </body>

  </html>

ログイン後にコピー

上記のコードでは、Swagger UI の JavaScript ライブラリを使用します。これを通じて、生成された APIドキュメントは美しい HTML ページの形式で表示されます。

API ドキュメントを示すサンプルページを以下に示します:

PHP と Swagger を使用して API ドキュメントを生成する方法

##5. 結論

Swagger を使用すると、API の生成と管理を簡単にドキュメント化できます。この記事では、PHP と Swagger を使用して API ドキュメントを生成する方法を紹介します。手順には、Swagger のインストールと構成、Swagger を使用した API ドキュメントの生成、Swagger UI を使用した API ドキュメントの表示が含まれます。この記事で紹介した後、読者は Swagger を使用して独自の API ドキュメントを簡単に生成できると思います。

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