PHP で OAS ベースの API ドキュメントを使用する方法-PHPチュートリアル-php.cn

PHP で OAS ベースの API ドキュメントを使用する方法

WBOY

リリース： 2023-06-17 11:14:01

オリジナル

1153 人が閲覧しました

インターネットの急速な発展に伴い、API (Application Programming Interface) は不可欠な要素になりました。 API の機能は、さまざまなアプリケーション間の対話と通信を可能にして、データ共有とビジネス接続を実現することです。 API の増加と拡張に伴い、API ドキュメントをどのように効果的に管理および維持するかが解決すべき問題となっています。この点で、OAS (OpenAPI 仕様) に基づく API ドキュメントは有効な管理方法となっています。次に、PHP で OAS ベースの API ドキュメントを使用する方法を紹介します。

1. OAS とは

OAS は OpenAPI 仕様の略称で、Swagger 仕様とも呼ばれます。 OAS は API を定義するための言語で、JSON または YAML 形式に基づいており、効果的な API ドキュメントとクライアントコードを作成および生成するための RESTful API の仕様を定義するために使用されます。

2. OAS ドキュメントの書き方

Swagger エディタを使用して OAS ドキュメントを作成できますが、同時に OAS は API リクエストの定義など、いくつかの仕様要件も提供します。レスポンス、パラメータ、その他の形式。以下は、OAS に基づいて API ドキュメントを作成する基本的な例です。

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Example API
  description: "This is an example API for demonstration purposes."
paths:
  /example:
    get:
      summary: Example Endpoint
      description: "This endpoint returns an example response."
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  example_property:
                    type: string

ログイン後にコピー

OAS ドキュメントでは、URL、リクエストとレスポンスの形式などの API の基本情報を定義する必要があります。上記は簡単な例であり、/example という名前のエンドポイントが含まれており、JSON 形式で応答オブジェクトを返します。

3. OAS ベースの API ドキュメントの使用方法

OAS ベースの API ドキュメントを使用する前に、OAS ドキュメントを解析および検証する方法を知っておく必要があります。現在、OpenAPI Generator、Swagger Codegen、Swagger UI など、このタスクの実現に役立つオープンソースツールやライブラリが多数あります。ここでは、Swagger UI を使用して、OAS ベースの API ドキュメントの使用方法を示します。

Swagger UI をダウンロードし、PHP プロジェクトのパブリックフォルダーに抽出します。最新バージョンは、Swagger UI の GitHub ページからダウンロードできます。
OAS ドキュメントを Swagger UI が配置されているパブリックディレクトリにコピーし、swagger.json という名前を付けます。
index.html ファイルを編集し、その中の URL を swagger.json ファイルのパスに変更します。
PHP で Swagger UI を使用するには、PHP ファイルに次のコードを含める必要があります:

<!DOCTYPE html>
<html>
<head>
    <title>My API documentation</title>
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="swagger-ui/swagger-ui-bundle.js"></script>
    <script src="swagger-ui/swagger-ui-standalone-preset.js"></script>
    <script>
        window.onload = function() {
          const ui = SwaggerUIBundle({
            url: "./swagger.json",
            dom_id: "#swagger-ui",
            presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
            layout: "StandaloneLayout"
          })
        }
    </script>
</body>
</html>

ログイン後にコピー

この時点で、Swagger UI にアクセスして理解してテストできます。今すぐあなたの API を見つけてください。 Swagger UI は、OAS ドキュメントに基づいて API ドキュメントを自動的に生成し、UI で API リクエストとレスポンスをテストできます。

4. 概要

この記事では、PHP で OAS ベースの API ドキュメントを使用する方法を紹介しました。 OAS ベースの API ドキュメントは、API の維持および管理を改善するのに役立つ効果的な API ドキュメント管理方法です。 OAS ドキュメントの作成と使用についてさらに詳しく知りたい場合は、OAS 公式ドキュメントを参照し、いくつかのオープンソースツールを使用して実装およびテストすることをお勧めします。

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