Next.js でデータアプリの OpenAPI 仕様を使用する

このドキュメントでは、データアプリの OpenAPI 仕様を使用してクライアントコードを生成し、Next.js アプリケーションを開発する方法を紹介します。

あなたが始める前に

Next.js で OpenAPI 仕様を使用する前に、次のものを用意してください。

TiDB クラスター。詳細については、 TiDB サーバーレスクラスターを作成するまたはTiDB専用クラスターを作成するを参照してください。
Node.js
ネプ
糸

このドキュメントでは、TiDB Serverless クラスターを例として使用します。

ステップ1. データを準備する

まず、TiDB クラスターにテーブルtest.repositoryを作成し、そこにサンプルデータを挿入します。次の例では、デモ用のデータとして、PingCAP によって開発されたオープンソースプロジェクトをいくつか挿入します。

SQL ステートメントを実行するには、 TiDB Cloudコンソールのチャット2クエリ使用できます。

-- Select the database
USE test;

-- Create the table
CREATE TABLE repository (
        id int NOT NULL PRIMARY KEY AUTO_INCREMENT,
        name varchar(64) NOT NULL,
        url varchar(256) NOT NULL
);

-- Insert some sample data into the table
INSERT INTO repository (name, url)
VALUES ('tidb', 'https://github.com/pingcap/tidb'),
        ('tikv', 'https://github.com/tikv/tikv'),
        ('pd', 'https://github.com/tikv/pd'),
        ('tiflash', 'https://github.com/pingcap/tiflash');

ステップ2. データアプリを作成する

データが挿入されたら、 TiDB Cloudコンソールのデータサービスページに移動します。TiDB クラスターにリンクするデータアプリを作成し、データアプリの API キーを作成してから、データアプリにGET /repositoriesエンドポイントを作成します。このエンドポイントに対応する SQL ステートメントは次のようになります。これは、 test.repositoryテーブルからすべての行を取得します。

SELECT * FROM test.repository;

詳細についてはデータサービスを始める参照してください。

ステップ3. クライアントコードを生成する

以下では、Next.js を例として使用し、データアプリの OpenAPI 仕様を使用してクライアントコードを生成する方法を説明します。

hello-reposという名前の Next.js プロジェクトを作成します。
公式テンプレートを使用して Next.js プロジェクトを作成するには、次のコマンドを使用し、プロンプトが表示されたらすべてのデフォルトオプションをそのままにします。
```
yarn create next-app hello-repos
```
次のコマンドを使用して、新しく作成したプロジェクトにディレクトリを変更します。
```
cd hello-repos
```
依存関係をインストールします。
このドキュメントでは、 OpenAPI ジェネレーター使用して、OpenAPI 仕様から API クライアントライブラリを自動的に生成します。
OpenAPI Generator を開発依存関係としてインストールするには、次のコマンドを実行します。
```
yarn add @openapitools/openapi-generator-cli --dev
```

OpenAPI 仕様をダウンロードし、 oas/doc.jsonとして保存します。

TiDB Cloud データサービスページで、左側のペインにあるデータアプリ名をクリックして、アプリ設定を表示します。
API 仕様領域で、 「ダウンロード」をクリックし、JSON 形式を選択して、プロンプトが表示されたら「承認」をクリックします。
ダウンロードしたファイルをhello-reposプロジェクトディレクトリにoas/doc.jsonとして保存します。

詳細についてはOpenAPI仕様をダウンロードする参照してください。

oas/doc.jsonファイルの構造は次のとおりです。

{
  "openapi": "3.0.3",
  "components": {
    "schemas": {
      "getRepositoriesResponse": {
        "properties": {
          "data": {
            "properties": {
              "columns": { ... },
              "result": { ... },
              "rows": {
                "items": {
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    }
...
  "paths": {
    "/repositories": {
      "get": {
        "operationId": "getRepositories",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/getRepositoriesResponse"
                }
              }
            },
            "description": "OK"
          },
...

クライアントコードを生成します。
```
yarn run openapi-generator-cli generate -i oas/doc.json --generator-name typescript-fetch -o gen/api
```
このコマンドは、 oas/doc.json仕様を入力として使用してクライアントコードを生成し、クライアントコードをgen/apiディレクトリに出力します。

ステップ4. Next.jsアプリケーションを開発する

生成されたクライアントコードを使用して、Next.js アプリケーションを開発できます。

hello-reposプロジェクトディレクトリで、次の変数を含む.env.localファイルを作成し、変数の値をデータアプリの公開キーと秘密キーに設定します。
```
TIDBCLOUD_DATA_SERVICE_PUBLIC_KEY=YOUR_PUBLIC_KEY
TIDBCLOUD_DATA_SERVICE_PRIVATE_KEY=YOUR_PRIVATE_KEY
```
データアプリの API キーを作成するには、 APIキーを作成する参照してください。

hello-reposプロジェクトディレクトリで、 app/page.tsxの内容を次のコードに置き換えます。このコードは、 GET /repositoriesエンドポイントからデータを取得してレンダリングします。

import {DefaultApi, Configuration} from "../gen/api"

export default async function Home() {
  const config = new Configuration({
    username: process.env.TIDBCLOUD_DATA_SERVICE_PUBLIC_KEY,
    password: process.env.TIDBCLOUD_DATA_SERVICE_PRIVATE_KEY,
  });
  const apiClient = new DefaultApi(config);
  const resp = await apiClient.getRepositories();
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <ul className="font-mono text-2xl">
        {resp.data.rows.map((repo) => (
          <a href={repo.url}>
            <li key={repo.id}>{repo.name}</li>
          </a>
        ))}
      </ul>
    </main>
  )
}

注記：
データアプリのリンクされたクラスタが異なるリージョンでホストされている場合、ダウンロードした OpenAPI 仕様ファイルのserversセクションに複数の項目が表示されます。この場合、 configオブジェクトでエンドポイントパスを次のように構成する必要もあります。
const config = new Configuration({
    username: process.env.TIDBCLOUD_DATA_SERVICE_PUBLIC_KEY,
    password: process.env.TIDBCLOUD_DATA_SERVICE_PRIVATE_KEY,
    basePath: "https://${YOUR_REGION}.data.dev.tidbcloud.com/api/v1beta/app/${YOUR_DATA_APP_ID}/endpoint"
  });
basePathデータアプリの実際のエンドポイントパスに置き換えてください。 ${YOUR_REGION}と{YOUR_DATA_APP_ID}を取得するには、エンドポイントのプロパティパネルでエンドポイント URLを確認します。

ステップ5. Next.jsアプリケーションをプレビューする

注記：
プレビューする前に、必要な依存関係がすべてインストールされ、正しく構成されていることを確認してください。

ローカル開発サーバーでアプリケーションをプレビューするには、次のコマンドを実行します。

yarn dev

その後、ブラウザでhttp://ローカルホスト:3000開き、ページに表示されるtest.repositoryデータベースのデータを確認できます。

Next.js でデータ アプリの OpenAPI 仕様を使用する