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

OpenAPI 仕様の生成

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

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

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

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

OpenAPI エンドポイントを作成するには、バックエンドプロジェクト内で SquidService ベースクラスを拡張したサービスに @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 仕様書を locally 閲覧できます:

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 仕様書を閲覧できます:

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 仕様書を閲覧できます:

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

エンドポイントの監視​

Open API コントローラー、仕様書、および利用状況を確認するには、Squid Console の Backend タブに移動し、OpenAPI をクリックしてください。

API 仕様のカスタマイズ​

OpenAPI 仕様をさらにカスタマイズおよび強化するために、プロジェクトに tsoa.json 設定ファイルを含めることができます。このファイルを使用すると、セキュリティ定義、コントローラーパス、仕様書出力ディレクトリなどの高度な設定を定義できます。

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"
  }
}

この設定により、プロジェクトは dist ディレクトリに OpenAPI 仕様書ファイルを出力し、apiKeyAuth という名前の API キー認証方式が定義されます。

エンドポイントへのセキュリティの追加​

API エンドポイントにセキュリティを適用するには、tsoa の @Security デコレーターを使用できます。このデコレーターは、個々のメソッドやクラス全体に追加して、クラス内のすべてのメソッドに適用できます。以下は、tsoa.json で定義された API キーを使用してエンドポイントを保護する例です:

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 デコレーターにより、apiKeyAuth セキュリティ定義が SecureExampleService 内のすべてのエンドポイントに適用されることが指定されています。これにより、クライアントはヘッダーに正しい API キーを含める必要があり、これにより該当エンドポイントにアクセスできるようになります。

まとめ​

tsoa.json ファイルを使用することで、OpenAPI 仕様書の生成をカスタマイズし、認証などの重要な機能を API に追加できます。なお、@Security デコレーターはセキュリティ要件を OpenAPI 仕様に反映させるだけであり、サービスメソッド内でセキュリティ認証情報を検証するロジックは別途実装する必要があることにご注意ください。

これらの設定を統合することで、API のセキュリティと機能性が向上し、安全に利用しやすくなります。