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

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

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ファイルの作成​

API仕様書の設定を行うために、バックエンドプロジェクトのルートに次の内容のtsoa.jsonファイルを作成してください:

{
  "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仕様書ファイルをdistディレクトリに出力し、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デコレーターが、SecureExampleService内のすべてのエンドポイントに対してapiKeyAuthセキュリティ定義を適用することを指定しています。つまり、クライアントはこれらのエンドポイントにアクセスするために、正しいAPIキーをヘッダーに含める必要があります。

結論​

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

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