メインコンテンツまでスキップ

OpenAPI 仕様を生成する

Squid Backend SDK は、OpenAPI 仕様を自動生成し、カスタム API を公開するためのデコレーターを提供します。​

Squid を使うと、機能が豊富な API を作成できます。

OpenAPI Specification（OAS）は HTTP API のための標準的で言語非依存なインターフェースを定義しており、人間とコンピューターの両方がサービスの機能を発見して理解できるようにします。これは、実装の詳細を知らなくてもリモートサービスを理解して操作するために開発者が必要とする情報を提供します。

Squid Backend SDK は tsoa デコレーターを使用して OpenAPI 仕様を生成します。Tsoa は OpenAPI コンパイラを統合したフレームワークで、TypeScript を使用して Node.js のサーバーサイドアプリケーションを構築できます。利用可能なデコレーターの詳細については、tsoa documentation を参照してください。

OpenAPI エンドポイントを作成するには、バックエンドプロジェクト内で SquidService ベースクラスを継承する service に @Route デコレーターを追加し、OpenAPI エンドポイント関数に適切なデコレーターを追加します。

Backend code
import { SquidService } from '@squidcloud/backend';
import { Get, Query, Route } from 'tsoa';

@Route('example')
export class ExampleService extends SquidService {
  @Get('echo')
  echo(@Query() message: string): Promise<string> {
    return this.createOpenApiResponse(message, 200);
  }
}

エンドポイントの場所​

ローカル​

ローカルで開発する場合、上記のエンドポイントは次の形式になります。example は @Route デコレーターの値で、echo は関数名です。

https://[YOUR_APP_ID]-dev-[YOUR_SQUID_DEVELOPER_ID].[APP_REGION].squid.cloud/openapi/example/echo

次の形式の URL で ローカル の詳細な OpenAPI spec を確認できます。

https://[YOUR_APP_ID]-dev-[YOUR_SQUID_DEVELOPER_ID].[APP_REGION].squid.cloud/openapi/spec.json

デプロイ済み​

dev にデプロイした場合、上記のエンドポイントは次の形式になります。example は @Route デコレーターの値で、echo は関数名です。

https://[YOUR_APP_ID]-dev.[APP_REGION].squid.cloud/openapi/example/echo

次の形式の URL でデプロイ済みの dev OpenAPI spec を確認できます。

https://[YOUR_APP_ID]-dev.[APP_REGION].squid.cloud/openapi/spec.json

prod にデプロイした場合、エンドポイントは次の形式になります。example は @Route デコレーターの値で、echo は関数名です。

https://[YOUR_APP_ID].[APP_REGION].squid.cloud/openapi/example/echo

次の形式の URL でデプロイ済みの prod OpenAPI spec を確認します。

https://[YOUR_APP_ID].[APP_REGION].squid.cloud/openapi/spec.json

エンドポイントをモニタリングする​

Open API controllers、specs、usage を表示するには、Squid Console の Backend タブに移動して OpenAPI をクリックします。

API Specification をカスタマイズする​

OpenAPI 仕様をさらにカスタマイズして強化するには、プロジェクトに tsoa.json 設定ファイルを含めることができます。このファイルにより、security definitions、controllers paths、specification の出力ディレクトリなどの高度な設定を定義できます。

tsoa.json ファイルの作成​

バックエンドプロジェクトのルートに tsoa.json ファイルを作成し、次の内容で API 仕様を設定します。

{
  "entryFile": "src/service/index.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": ["src/**/*.ts"],
  "spec": {
    "outputDirectory": "dist",
    "specVersion": 3,
    "securityDefinitions": {
      "apiKeyAuth": {
        "type": "apiKey",
        "name": "my-api-key-header",
        "in": "header"
      }
    }
  },
  "routes": {
    "routesDir": "dist",
    "middlewareTemplate": "./node_modules/@squidcloud/local-backend/dist/local-backend/openapi-template.hbs"
  }
}

この設定により、OpenAPI specification ファイルを dist ディレクトリに出力し、apiKeyAuth という名前の API key 認証方式を定義します。

エンドポイントに Security を追加する​

API エンドポイントに Security を強制するには、tsoa の @Security デコレーターを使用できます。このデコレーターは個々のメソッドに追加することも、クラスレベルで追加してクラス内のすべてのメソッドに適用することもできます。以下は tsoa.json で定義した API key を使ってエンドポイントを保護する例です。

Backend code
import { Get, Route, Security } from 'tsoa';

@Route('secure-example')
@Security('apiKeyAuth')
export class SecureExampleService {
  @Get('data')
  secureData(): Promise<string> {
    // Method implementation goes here
    return Promise.resolve('Secure data accessed');
  }
}

上記の例では、@Security デコレーターにより、SecureExampleService 内のすべてのエンドポイントに apiKeyAuth の security definition が適用されることが指定されています。これは、クライアントがこれらのエンドポイントにアクセスするために、ヘッダーに正しい API key を含める必要があることを意味します。

結論​

tsoa.json ファイルを使用することで、OpenAPI 仕様の生成をカスタマイズし、API に authentication のような重要機能を追加できます。なお、@Security デコレーターは OpenAPI spec に security 要件を追加するだけであり、service メソッド内で security credentials を検証するロジックは引き続き実装する必要があります。

これらの設定を統合することで API の security と機能性が向上し、堅牢になり、安全に使いやすくなります。