PHP と Swagger を使用して API ドキュメントを生成する方法
- 王林オリジナル
- 2023-05-11 16:40:421740ブラウズ
インターネットの急速な発展に伴い、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 ドキュメントを生成する方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。