API Platform
よしたにです。
信州の端っこで Symfony を使い続けて15年ぐらい経ちました。
最近では API Platform を、Next.js などのバックエンドとして使うことが増えてきました。ただし、現状では進化が早く、継続的にアップデートをしていく必要があります。
弊社では、クライアントとして OpenAPI Client Generator の TypeScript (Fetch) を用いております。
https://github.com/OpenAPITools/openapi-generator/tree/master
OpenAPI Client Generator は Type の生成に加え、各エンドポイント毎にクラスのメソッドを生成するため、使いやすいと考えていますが、JSON+LDに対応しておりません。そのため、json のフォーマットに切り替えて利用しております。
サーバー側
json+ld を無効化するには、api_platform.yaml を修正します。
api_platform.yaml の formats の初期状態は未定義で、黙字的に jsonld が利用されるようです。
これを以下のようにjsonを有効にします。
一行目にあるフォーマットがデフォルトとして扱われるとのことです。
api_platform:
formats:
# jsonld: ['application/ld+json']
json: ['application/json']
html: ['text/html']
以下のコマンドで json ベースの openapi の定義が出力されます。
bin/console api:openapi:export
画面上で確認する場合は以下のURLで出力されたものと一致しました。
正直、 formats と docs_formats の関係がいまいちわかっていません。
クライアント側
ここでは、便宜上プロジェクトが backend と frontend というディレクトリに分かれているとして、 frontend 側に保存するとすれば以下のようになろうかと思います。
cd backend
bin/console api:openapi:export > ../frontend/config/openapi.json
次に、フロント側でパッケージをインストールしクライアントを生成していきます。
cd frontend
npm install --save-dev @openapitools/openapi-generator-cli
package.json の scripts にダウンロードと生成のスクリプトを追記します。
{
"scripts": {
"openapi:validate": "openapi-generator-cli validate -i './config/openapi.json'",
"openapi:generate": "openapi-generator-cli generate -g typescript-fetch -i './config/openapi.json' -o './src/openapi'"
}
}
npm run openapi:validate
npm run openapi:generate
これでクライアントが生成されます。
問題は json を使うことにより、json+ldが持っていたコレクションを扱う処理が無くなってしまうことです。こちらは ApiPlatform の内部の ApiPlatform\JsonApi\Serializer\CollectionNormalizer のコードを流用して独自の Normalizer を作成して対応しました。この点は別途まとめたいと思います。