Swagger-phpとは？その使い方を徹底解説

phpプロジェクトではどうやってSwaggerの仕様書を生成する場合、最初に頭に浮かぶのは、いつもSwagger-phpになりますね。それでは、Swagger-phpとはなんですか？どうやってSwagger-phpを使って仕様書を生成しますか？本文では、これらの疑問を取り上げ、その詳細を皆さんに紹介します。

Swagger-phpとは

swagger-phpは、PHPでSwagger（現在はOpenAPI Specificationとして知られています）を使用してAPIドキュメントを生成するためのツールです。swagger-phpは、PHP開発者がSwagger（OpenAPI）仕様に基づいたAPIドキュメントを作成するのを支援します。このツールは、PHPのコードからSwagger（OpenAPI）仕様を生成することができます。これにより、開発者はAPIのエンドポイントやリクエストとレスポンスの定義をコード内で行い、自動的にSwagger（OpenAPI）仕様を生成することができます。

Swagger-phpの特徴

1.Swagger-phpはOpenAPIのバージョン3.0と3.1の仕様書を生成できます。

2.Swagger-phpはphpのソースコードでAPIを記録することを許可します。

3.Swagger-phpの注釈の属性は、docblocksかphp 8.1になります。

詳細ガイド：Swagger-phpの使い方

この部分では、Swagger-phpの使い方がまだ分からないユーザーに対して、Swagger-phpを徹底的に使える方法を紹介します。

Swagger-phpのインストール

 composer require zircote/swagger-php

ユーティリティの使用

<?phprequire("vendor/autoload.php");
$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

Controllerの使用例

<?phpuse OpenApi\Annotations as OA;/**
 * @OA\Info(
 *     title="My First API",
 *     version="0.1"
 * )
 */class OpenApi {}class MyController {/**
     * @OA\Get(
     *     path="/api/data.json",
     *     @OA\Response(
     *         response="200",
     *         description="The data"
     *     )
     * )
     */public function getResource() {// ...}}

仕様書を生成

 ./bin/openapi src -o openapi.yaml

PHPの属性（attributes）の利用について

PHPの属性（Attributes）は、PHP 8以降で導入された新機能であり、コードにメタデータを付加するための方法として、クラス、メソッド、プロパティ、関数などに適用することができます。属性は、コードの動作に直接的な影響を与えるわけではなく、主にドキュメント化やフレームワークやライブラリのメタデータとして使用されます。

PHPの属性は、フレームワークやライブラリの開発において、ルーティング、バリデーション、シリアライゼーション、キャッシングなどの機能を追加するために使用されることがあります。また、属性を使用することで、IDEや静的解析ツールが属性に基づいた補完や警告を提供することもできます。

PHP属性は、コードのメタデータを明示的に定義するための強力な手段であり、コードの可読性、保守性、および拡張性を向上させることができます。

以下に、PHP属性の基本的な使用方法と一般的なシナリオをいくつか紹介します。

属性の定義:

#[Attribute]
class MyAttribute {
    // 属性のプロパティやメソッドを定義
}

属性の適用:

#[MyAttribute]
class MyClass {
    #[MyAttribute]
    public $myProperty;

    #[MyAttribute]
    public function myMethod(#[MyAttribute] $param) {
        // メソッドの本体
    }
}

属性のパラメータ:

#[Attribute(Attribute::TARGET_PROPERTY)]
class MyAttribute {
    public function __construct(public string $value) {
        // パラメータの初期化
    }
}

#[MyAttribute('example')]
public $myProperty;

属性の取得:

$reflector = new ReflectionClass('MyClass');
$attributes = $reflector->getAttributes(MyAttribute::class);
foreach ($attributes as $attribute) {
    $instance = $attribute->newInstance();
    // 属性を使用した処理
}

メタデータの利用:

#[Attribute]
class Route {
    public function __construct(public string $path) {}
}

#[Route('/users')]
class UsersController {
    #[Route('/{id}', method: 'GET')]
    public function show($id) {
        // ルーティングに基づいた処理
    }
}

上記の例では、MyAttributeという名前の属性を定義し、MyClassのクラス、プロパティ、およびメソッドに適用しています。属性は、リフレクションを使用して取得し、属性のインスタンスを作成してメタデータを利用することもできます。

API仕様書の共有

Swagger仕様書を生成した後、それをチームメンバーに共有することが多いと思います。このような場合、Swagger JSON かOpenAPI yamlのフォーマットで共有することが多いのですが、それはやや時代遅れな感じがしています。

button

ここでApidogという完璧なAPI管理ツールとして、Swagger JSONやYAMLデータに基づいて可読性が高いAPI仕様書を即座に生成できます。また、API共有機能でこのAPI仕様書を簡単に共有することができます。

また、ApidogはAPIライフサイクル管理ツールとして、様々な機能も提供しています。

APIの設計と仕様書生成：Apidogは、一番使いやすいAPI設計ツールとして、コードなしでも直感的にAPIを設計できるので、OpenAPIやSwagger仕様書を快適に生成してくれます。

APIの管理と単体テスト：Apidogを使ってAPIを効率よく管理することができ、APIリクエストを送信したら、レスポンスを検証したりすることもできるので、単体テストも非常に簡単な作業になります。

APIテスト自動化：また、Apidogは自動テストをサポートし、CI/CDにも対応できます。この機能を使って、スレッド数などを設定することで、APIの負荷テスト、APIテストの自動化をも簡単に実現できます。

button