ThinkPHP6 を使用して API ドキュメントを自動生成する

API がますます広く使用されるようになるにつれて、API ドキュメントの自動生成は不可欠なツールになりました。この記事では、ThinkPHP6 フレームワークを使用して API ドキュメントを自動生成する方法を紹介します。

1. ThinkPHP6 フレームワークの概要

ThinkPHP6 は、PHP 言語を使用して開発された、効率的、シンプル、便利、および柔軟なオープン ソース フレームワークです。オブジェクト指向開発モデルを採用し、MVC (Model-View-Controller) アーキテクチャをサポートし、ルーティング、キャッシュ、検証、テンプレート エンジンなどの強力な機能を備えています。

2. Swagger UI のインストール

Swagger は API ドキュメントの自動生成ツールで、API ドキュメントを自動的に生成し、API の実行結果をデモンストレーションするための Web インターフェイスを提供します。 ThinkPHP6 を使用して API ドキュメントを自動生成する場合、最初に Swagger をインストールする必要があります。

Swagger は Composer ツールを通じてインストールできます。コマンド ラインに次のように入力します:

composer require zircote/swagger-php

インストールが完了したら、プロジェクトのルート ディレクトリに Swagger 構成ファイルを作成し、それに swagger.php という名前を付けます:

<?php
return [
    'swagger' => [
        'api' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'paths' => [
            APP_PATH . '/',
        ],
        'exclude' => [
        ],
        'swagger-ui' => [
            'title' => 'API文档',  //API文档的标题
        ],
        'securityDefinitions' => [
        ],
    ],
];

3. API ドキュメントを定義します。 comments

Swagger が API ドキュメントを自動的に識別して生成するには、対応するコメントをコードに追加する必要があります。 ThinkPHP6 は、API ドキュメントを定義するためのカスタム コメント形式を提供します。

コントローラーで API ドキュメント コメントを定義します:

<?php
declare(strict_types=1);

namespace appcontroller;

class Example
{
    /**
     * @OAGet(
     *      path="/example/index",
     *      operationId="exampleIndex",
     *      tags={"Example"},
     *      summary="示例接口",
     *      description="这是一个示例接口",
     *      @OAResponse(
     *          response=200,
     *          description="操作成功",
     *      ),
     *      @OAResponse(
     *          response=401,
     *          description="未授权",
     *      ),
     *      security={
     *          {"Bearer": {}}
     *      }
     * )
     */
    public function index()
    {
        //接口代码
    }
}

上記のコードでは、@OA で始まるコメント タグが Swagger の正規形式に解析されます。このうち、@OAGet は API のリクエストメソッドを Get メソッドとして定義し、path は API のパスを定義し、operationId はオペレーションの ID を定義し、tags は API が属するタグを定義し、summary は API の概要を定義します。 ; description は API の詳細な説明を定義します ; @OAResponse は API の応答結果とステータス コードを定義します; security は API のアクセス権限を定義します

4. API ドキュメントの生成

API ドキュメントのアノテーションを定義した後、Swagger を使用して API ドキュメントを生成できます。コマンド ラインで次のコマンドを入力します。

php think swagger:export --output public/swagger.json

このコマンドは、API ドキュメントをパブリック ディレクトリの swagger.json ファイルに保存します。

5. API ドキュメントへのアクセス

Swagger UI を使用して API ドキュメントを表示します。 Swagger UI プロジェクトを Web サーバーにデプロイすることも、ローカルで実行することもできます。

ローカルで実行する場合、次のコマンドを使用して Swagger UI サービスをすぐに開始できます:

docker run --rm -p 8080:8080 -e SWAGGER_JSON=/data/swagger.json -v /path/to/swagger.json:/data/swagger.json swaggerapi/swagger-ui

このうち、/path/to/swagger.json は Swagger の絶対パスです。 json ファイル。

ブラウザで http://localhost:8080 にアクセスして、API ドキュメントを表示します。

6. 概要

この記事では、ThinkPHP6 フレームワークと Swagger を使用して API ドキュメントを自動生成する方法を紹介します。 API ドキュメントを自動生成することで、開発効率が向上し、メンテナンスコストが削減されます。この記事の導入により、読者は既に ThinkPHP6 フレームワークと Swagger を上手に使って API ドキュメントの自動生成を実現できるようになったと思います。

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