OpenAPIをつかってSynergy!のAPIライブラリを生成する方法

TOPICS:

Posted By: nishikiori 2023年8月28日

はじめに

以前はphpでcURLを使ってAPIを呼び出すということをしていましたが今回、OpenAPIを使う機会があって使ってみたらAPIのライブラリ作成やAPIの説明ドキュメントなどを一気に作ることができて便利だったのでその方法について説明していこうと思います。

OpenAPIとは

OpenAPI（以前はSwaggerという名称）は、APIを記述するためのオープンソースのフレームワークで、APIの設計、ビルド、ドキュメント化を簡素化するために使用されています。 OpenAPIは、APIの規格を定義するための仕様であり、APIの開発者、利用者がドキュメントを生成するために使用することができます。

Synergy!とは

シナジーマーケティングが提供する統合顧客管理システムです。顧客情報の一元管理を行いながら外部システムとの連携やアンケート、メール配信、LINE配信などを行うことができます。
APIを利用する場合、事前にSynergy!の利用登録が必要になります。利用登録についてはSynergy!公式ページよりお問い合わせください。

API仕様書を作成

OpenAPIでライブラリを作成するためにAPI仕様書が必要になります。仕様書にはAPIエンドポイント、HTTPメソッド、パラメータ、リクエストおよびレスポンスの形式、認証メカニズムなど、APIに関する情報を定義しながらjosnまたはyaml形式で記載していきます。ただ、今回はシナジーマーケティングがOpenAPIに合わせた仕様書を公式のAPIに関するページの一番上にあるダウンロードリンクから提供してくれるのでそれを使用します。
筆者はそれを知らずにAPIの仕様書を作ろうとしていましたがその仕様書の存在をしったときに結構後悔しました。

仕様書からライブラリを作成

dockerで実行する場合は以下のコマンドになります。生成する言語はphpで事前にdockerなどのインストールは済ませてください。またライブラリの管理でcomposerを使用するので使用するphpのバージョンと対応関係があることの確認も済ませてください。

docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \
    -i /local/sample.yaml \
    -o /local/sample \
    -g php

それぞれのオプションの説明をしていきます。

penapitools/openapi-generator-cli generate
コード生成のコマンドです。注意点としてはphpのバージョンによっては動作しない場合が最新ではない場合はこのリンクから動作するか確認してください。コード生成のバージョンを下げる場合は以下みたいに記述するとうまく動作すると思います。

openapitools/openapi-generator-cli:v5.1.1 generate

次に
-i /local/sample.yaml \
ですがこちらはjson,yamlで作成した仕様書のファイルを指定している部分です。今回は例のためsampleにしています。

さらにその下の
-o /local/sample \
ですがこちらは生成したライブラリを配置する部分になります。上の例だと作成されたライブラリはsampleフォルダに格納されます。

最後に
-g php
こちらは生成したい言語をしてします。

生成したライブラリを使ってみる

最後に生成したライブラリを使って全テーブルの定義取得を実行してみます。
まず初めにライブラリを使用するにはトークン周りの準備が必要になります。こちらのトークン周りの処理も提供されているのでこちらを参考にするとよいと思います。
それらを使った全テーブルの定義を取得するコードになります。

<?php

//ライブラリの呼び出し
require_once '/vendor/autoload.php';
//トークン周りの呼び出し、今回はAuthorization.phpというファイル名にしています。
require_once '/Authorization.php';
use OpenAPI\Client\Configuration;
use OpenAPI\Client\Api\DatabaseDefinitionApi;

class DbDefinition {
    public function main() {
        //データベース定義を取得
        $db = new DatabaseDefinitionApi(new GuzzleHttp\Client(), $this->setConfig());
        //CODEという引数はSynergy!の管理画面のAPI管理画面で確認した値になります
        return json_encode($db->listDatabaseDefinition('CODE'));
    }

    /**
     * トークンを設定
     */
    private function setConfig() {
        //こちらも同様に2つの引数はSynergy!の管理画面のAPI管理画面で確認した値になります
        $accessToken = Authorization::getAccessToken('KEY', 'SECRET');
        return Configuration::getDefaultConfiguration()->setAccessToken($accessToken);
    }
}

終わりに

APIの設計から実装は結構大変なイメージがありましたが設計書からコードを作成してくれるのは非常に便利だと思いました。今回はライブラリの生成まででしたがSynergy!では取得したテーブル定義を使ってAPIで使用する定義を設定していく必要がありますがそれは別の機会に説明しようと思います。