OpenAPI 仕様を生成する

TypeScript デコレーターを使って OpenAPI spec を自動生成し、REST API を公開します。

なぜ OpenAPI エンドポイントを使うのか

サードパーティ連携、モバイルクライアント、または Squid Client SDK を利用できない外部サービスのために、バックエンドを標準的な REST API として公開する必要があります。

OpenAPI がない場合、ルートの手動定義、spec ファイルの作成、CORS の設定、ドキュメントの同期をすべて手作業で行う必要があります。Squid の OpenAPI サポートでは、メソッドにデコレーターを付けるだけで、完全にドキュメント化された REST API を得られます。

// Backend: just decorators on a service method
@Route('orders')
export class OrderService extends SquidService {
  @Get('{orderId}')
  async getOrder(@Path() orderId: string): Promise<Order> {
    const order = await this.fetchOrder(orderId);
    return this.createOpenApiResponse(order);
  }
}

// Consumers call it as a standard REST endpoint:
// GET https://<your-app>.squid.cloud/openapi/orders/abc123

spec を手動で書く必要はありません。ルート設定も不要です。デコレーターを付けたメソッドだけで完了します。

概要

Squid は tsoa のデコレーターを使い、TypeScript コードから OpenAPI specifications を生成します。SquidService のサブクラス上のメソッドとしてエンドポイントを定義すると、Squid が spec を生成し、ルーティングを処理し、API を提供します。

OpenAPI エンドポイントを使うべき場面

ユースケース	推奨
外部コンシューマ向けに REST API を公開したい	OpenAPI endpoint
Squid Client SDK からバックエンド関数を呼び出したい	Executables を使用
データベース変更に反応したい	Triggers を使用
外部サービスからの HTTP コールバックを受けたい	Webhooks を使用

仕組み

SquidService を拡張したクラスに @Route を追加し、メソッドに HTTP メソッドデコレーターを付与します
Squid はデプロイ時にデコレーションされたメソッドを検出し、OpenAPI spec を生成します
外部コンシューマは標準的な HTTP リクエストでエンドポイントを呼び出します
Squid がリクエストをルーティングし、パラメータを抽出してメソッドを呼び出します
createOpenApiResponse() を使ってレスポンスを返します

クイックスタート

前提条件

squid init-backend で初期化された Squid backend プロジェクト
@squidcloud/backend パッケージがインストールされていること

Step 1: OpenAPI エンドポイントを作成する

サービスクラスに @Route デコレーター、メソッドに HTTP メソッドデコレーターを追加します。

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

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

Step 2: サービスを export する

サービス index ファイルからサービスが export されていることを確認します。

service/index.ts
export * from './example-service';

Step 3: バックエンドをデプロイする

squid deploy

Step 4: エンドポイントを呼び出す

curl "https://YOUR_APP_ID-dev.APP_REGION.squid.cloud/openapi/example/echo?message=hello"

レスポンス body は hello になります。

エンドポイント URL

OpenAPI では 2 種類のエンドポイントターゲットを使用します。

OpenAPI エンドポイントの仕様 (Specification)

OpenAPI エンドポイントの spec をダウンロードするには、ベース URL に /openapi/spec.json を付けます。

エンドポイント本体

各エンドポイントは、ベース URL に /openapi/{route}/{method} のテンプレートを付けたルートで利用できます。

ベース URL

ベース URL は、バックエンドの実行方法によって変わります。

ローカル開発

ローカルで開発する場合、エンドポイントは次のベース URL を使用します。

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

したがって、対応するエンドポイントは次の通りです。

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

デプロイ環境

デプロイ環境のベース URL は、development 環境か production 環境かによって異なります。development 環境の URL には app ID の後に -dev が入る点だけが違います。

Dev:

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

Prod:

https://[YOUR_APP_ID].[APP_REGION].squid.cloud

たとえば Dev の対応するエンドポイントは次の通りです。

https://[YOUR_APP_ID]-dev.[APP_REGION].squid.cloud/openapi/spec.json
https://[YOUR_APP_ID]-dev.[APP_REGION].squid.cloud/openapi/{route}/{method}

モニタリング

Squid Console の Backend タブで、OpenAPI 配下から OpenAPI controller、spec、利用状況を確認できます。

コアコンセプト

HTTP メソッドデコレーター

Squid は tsoa デコレーターを通じて、標準的な HTTP メソッドすべてをサポートします。

Backend code
import { SquidService } from '@squidcloud/backend';
import { Body, Delete, Get, Patch, Path, Post, Put, Route } from 'tsoa';

interface Item {
  id: string;
  name: string;
  price: number;
}

interface CreateItemRequest {
  name: string;
  price: number;
}

@Route('items')
export class ItemService extends SquidService {
  @Get('{itemId}')
  async getItem(@Path() itemId: string): Promise<Item> {
    const item: Item = { id: itemId, name: 'Widget', price: 9.99 };
    return this.createOpenApiResponse(item);
  }

  @Post()
  async createItem(@Body() data: CreateItemRequest): Promise<Item> {
    const newItem: Item = { id: crypto.randomUUID(), ...data };
    return this.createOpenApiResponse(newItem, 201);
  }

  @Put('{itemId}')
  async replaceItem(@Path() itemId: string, @Body() data: Item): Promise<Item> {
    const updatedItem: Item = { ...data, id: itemId };
    return this.createOpenApiResponse(updatedItem);
  }

  @Patch('{itemId}')
  async updateItem(@Path() itemId: string, @Body() data: Partial<Item>): Promise<Item> {
    const updatedItem: Item = { id: itemId, name: data.name ?? 'Widget', price: data.price ?? 9.99 };
    return this.createOpenApiResponse(updatedItem);
  }

  @Delete('{itemId}')
  async deleteItem(@Path() itemId: string): Promise<void> {
    console.log(`Deleting item ${itemId}`);
    return this.createOpenApiResponse(undefined, 204);
  }
}

パラメータデコレーター

HTTP リクエストのさまざまな場所からデータを抽出します。

デコレーター	取得元	例
`@Path()`	URL パスセグメント	`/items/{itemId}`
`@Query()`	クエリ文字列	`?status=active`
`@Body()`	リクエスト body	JSON payload
`@Header()`	HTTP ヘッダー	`Authorization` header
`@UploadedFile(fieldName)`	単一ファイルアップロード	Form file input
`@UploadedFiles(fieldName)`	複数ファイルアップロード	Multi-file form input
`@FormField()`	フォームフィールドデータ	Form text input

すべてのデコレーターは tsoa から import します。

`createOpenApiResponse()`

カスタムのステータスコードやヘッダーを含むレスポンスを構築するためにこのメソッドを使います。

Backend code
// 200 with body (default)
return this.createOpenApiResponse({ id: '123', name: 'Widget' });

// 201 Created with custom header
return this.createOpenApiResponse({ id: 'new-item' }, 201, { 'x-custom-header': 'created' });

// 204 No Content
return this.createOpenApiResponse(undefined, 204);

// 404 Not Found
return this.createOpenApiResponse({ error: 'Resource not found' }, 404);

Parameters:

Parameter	Type	Description
`body`	`unknown` (optional)	レスポンス payload
`statusCode`	`number` (optional)	HTTP ステータスコード。body があればデフォルト 200、なければ 204
`headers`	`Record<string, unknown>` (optional)	レスポンスヘッダー

`throwOpenApiResponse()`

実行を即座に中断してレスポンスを返すためにこのメソッドを使います。認可失敗のような早期終了に便利です。

Backend code
@Get('protected')
async protectedEndpoint(): Promise<string> {
  const apiKey = this.context.headers?.['x-api-key'];
  if (!apiKey) {
    this.throwOpenApiResponse({ body: 'UNAUTHORIZED', statusCode: 401 });
  }
  return this.createOpenApiResponse('Secret data');
}

OpenAPI context

OpenAPI リクエストでは、this.context.openApiContext を通じて生のリクエスト詳細にアクセスできます。

Backend code
@Get('debug')
async debugRequest(): Promise<object> {
  const ctx = this.context.openApiContext!;
  return this.createOpenApiResponse({
    method: ctx.request.method,       // 'get', 'post', etc.
    path: ctx.request.path,           // '/debug'
    queryParams: ctx.request.queryParams,
    headers: ctx.request.headers,
    rawBody: ctx.request.rawBody,     // Raw request body string
  });
}

ファイル処理

ファイルのアップロード:

Backend code
import { SquidService } from '@squidcloud/backend';
import { Post, Route, UploadedFile, UploadedFiles } from 'tsoa';

@Route('files')
export class FileService extends SquidService {
  @Post('upload')
  async uploadFile(@UploadedFile() file: Express.Multer.File): Promise<object> {
    return this.createOpenApiResponse({
      filename: file.originalname,
      size: file.size,
      mimetype: file.mimetype,
    });
  }

  @Post('upload-multiple')
  async uploadFiles(@UploadedFiles() files: Express.Multer.File[]): Promise<object> {
    return this.createOpenApiResponse(files.map((f) => ({ name: f.originalname, size: f.size })));
  }
}

ファイルを返す:

@Produces デコレーターでレスポンスの MIME type を指定します。

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

@Route('files')
export class FileDownloadService extends SquidService {
  @Get('download')
  @Produces('application/octet-stream')
  async downloadFile(): Promise<File> {
    const content = new Uint8Array([72, 101, 108, 108, 111]);
    const file = new File([content], 'hello.txt', { type: 'text/plain' });
    return this.createOpenApiResponse(file);
  }
}

Spec ドキュメント用デコレーター

追加のメタデータで、生成される OpenAPI spec を強化します。

デコレーター	目的	例
`@Tags('label')`	spec 内でエンドポイントをグループ化	`@Tags('Users')`
`@Response(code, desc)`	取り得るレスポンスコードを記載	`@Response(404, 'Not found')`
`@Produces(mime)`	レスポンス MIME type を指定	`@Produces('application/octet-stream')`

認証と設定

`tsoa.json` による API spec の設定

backend プロジェクトのルートに tsoa.json ファイルを作成し、spec 生成をカスタマイズしたり、security scheme を定義したりします。

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

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

生成される spec で認証が必要であることを示すために @Security デコレーターを使います。クラスレベル（全エンドポイント）またはメソッドレベルで適用できます。

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

@Route('secure')
@Security('apiKeyAuth')
export class SecureService extends SquidService {
  @Get('data')
  async getData(): Promise<string> {
    return this.createOpenApiResponse('Secure data');
  }
}

Important

@Security デコレーターは OpenAPI spec 上で要件をドキュメント化するだけです。認証情報を検証するバリデーションロジックは、引き続きメソッド内で実装する必要があります。

実行時の認証 (Runtime authentication)

リクエスト context または組み込みの auth メソッドを使って、実行時に認証情報を検証します。

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

@Route('protected')
export class ProtectedService extends SquidService {
  @Get('with-api-key')
  async withApiKey(): Promise<string> {
    const apiKey = this.context.headers?.['x-api-key'];
    if (!apiKey || !Object.values(this.apiKeys).includes(apiKey)) {
      this.throwOpenApiResponse({ body: 'UNAUTHORIZED', statusCode: 401 });
    }
    return this.createOpenApiResponse('Authenticated data');
  }

  @Get('with-bearer')
  async withBearer(): Promise<string> {
    // Use built-in Squid auth (requires Squid auth integration)
    this.assertIsAuthenticated();
    const user = this.getUserAuth();
    return this.createOpenApiResponse(`Hello, ${user?.userId}`);
  }
}

認証メソッドの詳細は、using auth in the backend を参照してください。

エラーハンドリング

エラーレスポンスを返す

適切なステータスコードとともに createOpenApiResponse() を使います。

Backend code
@Get('{itemId}')
async getItem(@Path() itemId: string): Promise<Item> {
  if (!isValidId(itemId)) {
    return this.createOpenApiResponse({ error: `Invalid id: ${itemId}` }, 400);
  }

  const item = await this.findItem(itemId);
  if (!item) {
    return this.createOpenApiResponse({ error: 'Item not found' }, 404);
  }

  return this.createOpenApiResponse(item);
}

`throwOpenApiResponse()` で実行を中断する

早期終了（例: 認証失敗）では throwOpenApiResponse() を使って処理を即座に停止します。

Backend code
@Post('transfer')
async transfer(@Body() data: TransferRequest): Promise<object> {
  if (!this.isAuthenticated()) {
    this.throwOpenApiResponse({ body: 'UNAUTHORIZED', statusCode: 401 });
  }

  // This code only runs if authenticated
  const result = await this.processTransfer(data);
  return this.createOpenApiResponse(result);
}

未処理例外 (Unhandled exceptions)

メソッドが未処理のエラーを throw した場合、Squid は body にエラーメッセージを入れて 500 を返します。

Backend code
@Get('risky')
async riskyEndpoint(): Promise<string> {
  throw new Error('Something went wrong');
  // Returns: 500 with body "Something went wrong"
}

よくあるエラー

エラー	原因	解決策
404 `OPENAPI_CONTROLLER_NOT_FOUND`	ルートパスがどの `@Route` にも一致しない	URL が `@Route` とメソッドパスに一致しているか確認
エラーメッセージ付きの 500	メソッド内で未処理の例外が発生	try/catch と `createOpenApiResponse()` でエラーハンドリングする
パラメータ不足	必須パラメータがリクエストに含まれていない	query/path/body がデコレーターの期待と一致しているか確認

ベストプラクティス

セキュリティ

@Security は spec 上のドキュメントに過ぎないため、必ず実行時に認証情報を検証する
認証失敗時は throwOpenApiResponse() を使い、後続処理の実行を防ぐ
処理前に type と size を確認して ファイルアップロードを検証する

API 設計

説明的な route パスを使う（例: @Route('users')、@Route('u') ではない）
適切なステータスコードを返す（作成は 201、削除は 204、不正入力は 400）
生成される spec 内でエンドポイントを整理するために @Tags を使う
200 以外のステータスコードは @Response デコレーターでレスポンスをドキュメント化する

パフォーマンス

必要なデータだけを返して レスポンス payload を小さく保つ
無駄な処理を避けるため 入力を早めに検証する
JSON 以外のレスポンスでは @Produces で正しい content type を設定する

コード例

CRUD API

Backend code
import { SquidService } from '@squidcloud/backend';
import { Body, Delete, Get, Patch, Path, Post, Query, Response, Route, Tags } from 'tsoa';

interface Product {
  id: string;
  name: string;
  price: number;
}

@Route('products')
@Tags('Products')
export class ProductService extends SquidService {
  @Get()
  @Response(200, 'List of products')
  async listProducts(@Query() category?: string): Promise<Product[]> {
    const products = this.squid.collection<Product>('products');
    let query = products.query();
    if (category) {
      query = query.where('category', '==', category);
    }
    const results = await query.snapshot();
    return this.createOpenApiResponse(results);
  }

  @Get('{productId}')
  @Response(404, 'Product not found')
  async getProduct(@Path() productId: string): Promise<Product> {
    const ref = this.squid.collection<Product>('products').doc(productId);
    const product = await ref.snapshot();
    if (!product) {
      return this.createOpenApiResponse({ error: 'Product not found' }, 404);
    }
    return this.createOpenApiResponse(product);
  }

  @Post()
  @Response(201, 'Product created')
  async createProduct(@Body() data: Omit<Product, 'id'>): Promise<Product> {
    const id = crypto.randomUUID();
    const product = { id, ...data };
    await this.squid.collection<Product>('products').doc(id).insert(product);
    return this.createOpenApiResponse(product, 201);
  }

  @Patch('{productId}')
  async updateProduct(@Path() productId: string, @Body() data: Partial<Product>): Promise<Product> {
    const ref = this.squid.collection<Product>('products').doc(productId);
    await ref.update(data);
    const updated = await ref.snapshot();
    return this.createOpenApiResponse(updated);
  }

  @Delete('{productId}')
  @Response(204, 'Product deleted')
  async deleteProduct(@Path() productId: string): Promise<void> {
    await this.squid.collection<Product>('products').doc(productId).delete();
    return this.createOpenApiResponse(undefined, 204);
  }
}

API key で保護されたエンドポイント

Backend code
import { SquidService } from '@squidcloud/backend';
import { Body, Post, Route, Security } from 'tsoa';

@Route('webhooks')
@Security('apiKeyAuth')
export class WebhookReceiverService extends SquidService {
  @Post('ingest')
  async ingestData(@Body() payload: Record<string, unknown>): Promise<object> {
    // Validate API key at runtime
    const apiKey = this.context.headers?.['x-api-key'];
    if (!apiKey || !Object.values(this.apiKeys).includes(apiKey)) {
      this.throwOpenApiResponse({ body: 'UNAUTHORIZED', statusCode: 401 });
    }

    // Process the payload
    await this.squid.collection('events').doc(crypto.randomUUID()).insert({
      payload,
      receivedAt: new Date().toISOString(),
    });

    return this.createOpenApiResponse({ status: 'accepted' }, 201);
  }
}

外部 API プロキシ

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

@Route('weather')
export class WeatherProxyService extends SquidService {
  @Get('current')
  async getCurrentWeather(@Query() city: string): Promise<object> {
    const apiKey = this.secrets['WEATHER_API_KEY'] as string;

    const response = await fetch(`https://api.weather.example.com/v1/current?city=${encodeURIComponent(city)}`, { headers: { 'X-API-Key': apiKey } });

    if (!response.ok) {
      return this.createOpenApiResponse({ error: `Weather API returned ${response.status}` }, response.status);
    }

    const data = await response.json();
    return this.createOpenApiResponse(data);
  }
}

TypeScript デコレーターを使って OpenAPI spec を自動生成し、REST API を公開します。​

なぜ OpenAPI エンドポイントを使うのか​

概要​

OpenAPI エンドポイントを使うべき場面​

仕組み​

クイックスタート​

前提条件​

Step 1: OpenAPI エンドポイントを作成する​

Step 2: サービスを export する​

Step 3: バックエンドをデプロイする​

Step 4: エンドポイントを呼び出す​

エンドポイント URL​

OpenAPI エンドポイントの仕様 (Specification)​

エンドポイント本体​

ベース URL​

ローカル開発​

デプロイ環境​

モニタリング​

コアコンセプト​

HTTP メソッドデコレーター​

パラメータデコレーター​

createOpenApiResponse()​

throwOpenApiResponse()​

OpenAPI context​

ファイル処理​

Spec ドキュメント用デコレーター​

認証と設定​

tsoa.json による API spec の設定​

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

実行時の認証 (Runtime authentication)​

エラーハンドリング​

エラーレスポンスを返す​

throwOpenApiResponse() で実行を中断する​

未処理例外 (Unhandled exceptions)​

よくあるエラー​

ベストプラクティス​

セキュリティ​

API 設計​

パフォーマンス​

コード例​

CRUD API​

API key で保護されたエンドポイント​

外部 API プロキシ​

関連情報​