OpenAPI Generatorを使ってPHPのAPIクライアントを生成する方法

この記事では、OpenAPI Generatorを活用してPHPでAPIクライアントを生成する方法を紹介します。

弊社では数多くの広告媒体APIを利用しているのですが、PHPでのApiClientが提供されていない媒体があるためOpenAPI Generatorを使ってAPIクライアントを生成することで年に3～4回更新されるAPIに対応しています😊

1. OpenAPI Generatorとは

OpenAPI Generatorとは、OpenAPI仕様からAPIクライアントやAPIサーバーのコードを自動生成するツールです。

自動生成されるコードは、様々な言語に対応しておりAPIエンドポイントやリクエスト・レスポンスのモデルを扱うためのコードが生成されます。

2. OpenAPI Generatorのメリット

OpenAPI Generatorを使うメリットは以下になります。

API仕様からコードを自動生成できる

API仕様を元にクライアントコードを自動生成できるので、開発者はAPI仕様を意識することなくクライアントコードを生成できます。それに加え、テストコードやドキュメントも自動生成されるので開発者は開発スピードが上がることに加え手作業でのミスを減らすことができます。

API仕様の変更に対応しやすい

APIの仕様が変更された場合に、クライアントコードを再生成することで簡単に最新のAPI仕様に合わせることが可能です。

言語ごとに生成されるコードが最適化されている

言語ごとに生成されるコードが最適化されているため生成されたコードはある程度品質が保証されます。

3. OpenAPI GeneratorでAPIクライアントを生成する方法

生成する方法は簡単で下記コマンドを実行するだけで生成ができます。(Homebrew経由)

$ openapi-generator-cli generate -i <OpenAPI SpecificationのURL> -g <言語> -o <出力先>

このコマンドでは、<OpenAPI SpecificationのURL>にAPIの仕様ファイルのURL(URLではなくてファイル指定も可能)、<言語>に生成したいクライアントの言語、<出力先>に生成物を保存するディレクトリのパスを指定します。

Homebrew経由でなくてもDockerやnpm経由の方法もあり、詳しくは公式ドキュメントを参照してください。

公式ドキュメント：https://openapi-generator.tech/docs/installation

4. 【実践】ペットショップAPIクライアントを生成する

今回具体例として、ペットショップAPIクライアントをPHPのコードで生成してみます。

まず、生成するために必要な「OpenAPI SpecificationのURL」「言語」「出力先」を用意します。

4-1. 前提

OpenAPI SpecificationのURL：ペットショップAPIのOpenAPI Specificationを指定します。

OpenAPI GeneratorのサンプルページからペットショップAPIのOpenAPI SpecificationがあるのでこちらのURLを指定します。

ペットショップAPIのOpenAPI SpecificationのURL

言語：ここではわかりやすく言語としていますが正確にはOpenAPI Generatorが用意しているgenerate nameになります。

そのため今回はPHPのコードで生成したいのでphp-nextgenを指定します。 generate nameはGenerators Listに一覧があり自分の使いたい言語などによって選択できます。

php-nextgenについて詳しくはこちら：https://openapi-generator.tech/docs/generators/php-nextgen

出力先：生成されたコードを出力するディレクトリを指定します。

今回はopenapi-generator-php-sample-petstoreというディレクトリを作成してそこに生成されたコードを出力します。

4-2. 実行

まずはディレクトリを作成してその作成したディレクトリに移動しておきます。
```
$ mkdir openapi-generator-php-sample-petstore
$ cd openapi-generator-php-sample-petstore
```
今回Homebrew経由でAPIクライアントを生成するためOpenAPI Generatorのパッケージをインストールしておきます。
```
$ brew install openapi-generator
```

前提で用意したものを入れた下記コマンド実行するとAPIクライアントが自動生成されます。

$ openapi-generator generate -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -g php-nextgen -o ./

自動生成したコードがこちら：https://github.com/mako5656/openapi-generator-php-sample-petstore

5. 生成したAPIクライアントの使い方の例

生成したAPIクライアントを使うときは、自動生成されたドキュメントを参考に実装を行います。

■作成されたOpenAPI\Client\PetApiのドキュメント

Docs PetApi

例えば、OpenAPI\Client\PetApiクラスのaddPet()メソッドを使用して新しいペットを追加する書き方は以下の通りです。

■OpenAPI\Client\PetApiのaddPet()メソッドの使い方についてサンプルをそのまま下記に記載

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


// Configure OAuth2 access token for authorization: petstore_auth
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new OpenAPI\Client\Api\PetApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$pet = new \OpenAPI\Client\Model\Pet(); // \OpenAPI\Client\Model\Pet | Pet object that needs to be added to the store

try {
    $result = $apiInstance->addPet($pet);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling PetApi->addPet: ', $e->getMessage(), PHP_EOL;
}

行っていることとしては、最初に必要なライブラリの読み込みとOAuth2認証の設定を行い、次にPetApiインスタンスとペットオブジェクトを生成しています。そして、addPet()メソッドを使用してペットを追加し、エラーが発生した場合は適切なメッセージを表示するエラーハンドリングを実装しています。

自動生成したAPIクライアントを使うことで、このようにAPIのエンドポイントやリクエスト・レスポンスのモデルも簡単に扱うことができます。

6. まとめ

この記事では、OpenAPI Generatorを使用してPHPでAPIクライアントを生成する方法を、実践的な例を交えて紹介しました。 OpenAPI Generatorを活用することで、APIの自動生成が簡単になり開発者はAPIの新規作成や更新をすぐ行うことができます。これによって、手作業によるエラーを減らし開発スピードをはやくすることが可能です。今回例で使用したOpenAPI Specificationはすでに作成されているサンプルのものでしたが自分でカスタマイズすることが可能ですので是非試してみてください。

QUARTETCOM TECH BLOG カルテットコミュニケーションズ開発部ブログ